@indigoai-us/hq-cloud 5.19.1 → 5.21.0

package/dist/sources/internals.js

@@ -0,0 +1,39 @@
+/**
+ * Internal helpers shared between sources/list.ts and sources/get.ts.
+ *
+ * The S3 client factory hook exists so tests can inject an in-memory stub
+ * without standing up vi.mock for @aws-sdk/client-s3. Production code never
+ * calls the setter.
+ */
+import { S3Client } from "@aws-sdk/client-s3";
+function defaultFactory(ctx) {
+    return new S3Client({
+        region: ctx.region,
+        credentials: {
+            accessKeyId: ctx.credentials.accessKeyId,
+            secretAccessKey: ctx.credentials.secretAccessKey,
+            sessionToken: ctx.credentials.sessionToken,
+        },
+    });
+}
+let factory = defaultFactory;
+export function getS3Client(ctx) {
+    return factory(ctx);
+}
+/** Test hook: replace the S3 client factory. */
+export function _setSourcesS3Factory(f) {
+    factory = f;
+}
+/** Test hook: restore the default S3 client factory. */
+export function _resetSourcesS3Factory() {
+    factory = defaultFactory;
+}
+export async function streamToString(body) {
+    const stream = body;
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+//# sourceMappingURL=internals.js.map

package/dist/sources/internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.js","sourceRoot":"","sources":["../../src/sources/internals.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG9C,SAAS,cAAc,CAAC,GAAkB;IACxC,OAAO,IAAI,QAAQ,CAAC;QAClB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,WAAW,EAAE;YACX,WAAW,EAAE,GAAG,CAAC,WAAW,CAAC,WAAW;YACxC,eAAe,EAAE,GAAG,CAAC,WAAW,CAAC,eAAe;YAChD,YAAY,EAAE,GAAG,CAAC,WAAW,CAAC,YAAY;SAC3C;KACF,CAAC,CAAC;AACL,CAAC;AAED,IAAI,OAAO,GAAqC,cAAc,CAAC;AAE/D,MAAM,UAAU,WAAW,CAAC,GAAkB;IAC5C,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,oBAAoB,CAAC,CAAmC;IACtE,OAAO,GAAG,CAAC,CAAC;AACd,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,sBAAsB;IACpC,OAAO,GAAG,cAAc,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAa;IAChD,MAAM,MAAM,GAAG,IAAiC,CAAC;IACjD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACjD,CAAC"}

package/dist/sources/list.d.ts

@@ -0,0 +1,10 @@
+/**
+ * listSources — page through `sources/{channel}/` keys in an entity bucket
+ * and return typed summaries.
+ *
+ * The `.raw.json` siblings written by the sources-pipeline are skipped from
+ * the summary (callers fetch them via getSource({ includeRaw: true })).
+ */
+import type { ListSourcesOptions, ListSourcesResult } from "./types.js";
+export declare function listSources(opts: ListSourcesOptions): Promise<ListSourcesResult>;
+//# sourceMappingURL=list.d.ts.map

package/dist/sources/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/sources/list.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAsBpB,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqDtF"}

package/dist/sources/list.js

@@ -0,0 +1,76 @@
+/**
+ * listSources — page through `sources/{channel}/` keys in an entity bucket
+ * and return typed summaries.
+ *
+ * The `.raw.json` siblings written by the sources-pipeline are skipped from
+ * the summary (callers fetch them via getSource({ includeRaw: true })).
+ */
+import { GetObjectCommand, ListObjectsV2Command, } from "@aws-sdk/client-s3";
+import { assertSourceChannel } from "../schemas/source-channels.js";
+import { getS3Client, streamToString } from "./internals.js";
+import { parseFrontmatter } from "./parse.js";
+/**
+ * Strip the `sources/{channel}/` prefix and `.md` / `.raw.json` suffix from a key.
+ * Returns `null` if the key shape isn't recognised; the `isRawSibling` flag tells
+ * callers to skip pipeline-internal `.raw.json` companions from summaries.
+ */
+function deriveSourceId(key, prefix) {
+    if (!key.startsWith(prefix))
+        return null;
+    const tail = key.slice(prefix.length);
+    if (tail.endsWith(".raw.json")) {
+        return { sourceId: tail.slice(0, -".raw.json".length), isRawSibling: true };
+    }
+    if (tail.endsWith(".md")) {
+        return { sourceId: tail.slice(0, -".md".length), isRawSibling: false };
+    }
+    return null;
+}
+export async function listSources(opts) {
+    // Validate channel BEFORE any S3 call (acceptance criterion).
+    assertSourceChannel(opts.channel);
+    const client = getS3Client(opts.entity);
+    const prefix = `sources/${opts.channel}/`;
+    const response = await client.send(new ListObjectsV2Command({
+        Bucket: opts.entity.bucketName,
+        Prefix: prefix,
+        MaxKeys: opts.limit,
+        ContinuationToken: opts.continuationToken,
+    }));
+    const entries = [];
+    for (const obj of response.Contents ?? []) {
+        if (!obj.Key)
+            continue;
+        const derived = deriveSourceId(obj.Key, prefix);
+        if (!derived || derived.isRawSibling)
+            continue;
+        const summary = {
+            sourceId: derived.sourceId,
+            channel: opts.channel,
+            key: obj.Key,
+            lastModified: obj.LastModified ?? new Date(0),
+            size: obj.Size ?? 0,
+        };
+        if (opts.includeFrontmatter) {
+            try {
+                const get = await client.send(new GetObjectCommand({
+                    Bucket: opts.entity.bucketName,
+                    Key: obj.Key,
+                }));
+                const text = await streamToString(get.Body);
+                const fm = parseFrontmatter(text);
+                if (fm)
+                    summary.frontmatter = fm;
+            }
+            catch {
+                // Frontmatter fetch is best-effort; leave undefined on failure.
+            }
+        }
+        entries.push(summary);
+    }
+    return {
+        entries,
+        nextToken: response.IsTruncated ? response.NextContinuationToken : undefined,
+    };
+}
+//# sourceMappingURL=list.js.map

package/dist/sources/list.js.map

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

package/dist/sources/list.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Unit tests for sources/list.ts.
+ *
+ * Uses an in-memory S3Client stub installed via the internal `_setSourcesS3Factory`
+ * hook so we don't have to stand up vi.mock for @aws-sdk/client-s3.
+ */
+export {};
+//# sourceMappingURL=list.test.d.ts.map

package/dist/sources/list.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.test.d.ts","sourceRoot":"","sources":["../../src/sources/list.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/sources/list.test.js

@@ -0,0 +1,198 @@
+/**
+ * Unit tests for sources/list.ts.
+ *
+ * Uses an in-memory S3Client stub installed via the internal `_setSourcesS3Factory`
+ * hook so we don't have to stand up vi.mock for @aws-sdk/client-s3.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { GetObjectCommand, ListObjectsV2Command, } from "@aws-sdk/client-s3";
+import { listSources } from "./list.js";
+import { _setSourcesS3Factory, _resetSourcesS3Factory, } from "./internals.js";
+import { InvalidSourceChannelError } from "../schemas/source-channels.js";
+// ---------------------------------------------------------------------------
+// Fixtures + helpers
+// ---------------------------------------------------------------------------
+const ENTITY = {
+    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 MEETING_MD = `---
+source_id: abc
+source_type: meeting
+channel: meeting
+title: Hello
+---
+
+Body text.
+`;
+/** Build an in-memory S3 stub. Pagination is keyed by ContinuationToken (string offset). */
+function buildStub(objects, observed = { commands: [] }) {
+    async function send(command) {
+        observed.commands.push(command);
+        if (command instanceof ListObjectsV2Command) {
+            const { Prefix, MaxKeys, ContinuationToken } = command.input;
+            const filtered = objects.filter((o) => !Prefix || o.key.startsWith(Prefix));
+            const offset = ContinuationToken ? parseInt(ContinuationToken, 10) : 0;
+            const max = MaxKeys ?? 1000;
+            const page = filtered.slice(offset, offset + max);
+            const nextOffset = offset + page.length;
+            const truncated = nextOffset < filtered.length;
+            return {
+                Contents: page.map((o) => ({
+                    Key: o.key,
+                    Size: Buffer.byteLength(o.content, "utf-8"),
+                    LastModified: o.lastModified,
+                    ETag: '"mock"',
+                })),
+                IsTruncated: truncated,
+                NextContinuationToken: truncated ? String(nextOffset) : undefined,
+                $metadata: {},
+            };
+        }
+        if (command instanceof GetObjectCommand) {
+            const { Key } = command.input;
+            const found = objects.find((o) => o.key === Key);
+            if (!found) {
+                const err = new Error(`NoSuchKey: ${Key}`);
+                err.name = "NoSuchKey";
+                throw err;
+            }
+            const content = found.content;
+            async function* stream() {
+                yield Buffer.from(content, "utf-8");
+            }
+            return { Body: stream(), $metadata: {} };
+        }
+        throw new Error(`unhandled command: ${command.constructor?.name}`);
+    }
+    return { send };
+}
+function installStub(objects) {
+    const observed = { commands: [] };
+    const stub = buildStub(objects, observed);
+    _setSourcesS3Factory(() => stub);
+    return observed;
+}
+beforeEach(() => {
+    _resetSourcesS3Factory();
+});
+afterEach(() => {
+    _resetSourcesS3Factory();
+});
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe("listSources", () => {
+    it("happy path: lists one source and skips its .raw.json sibling", async () => {
+        installStub([
+            {
+                key: "sources/meeting/abc.md",
+                content: MEETING_MD,
+                lastModified: new Date("2026-03-15T14:00:00Z"),
+            },
+            {
+                key: "sources/meeting/abc.raw.json",
+                content: '{"raw": true}',
+                lastModified: new Date("2026-03-15T14:00:00Z"),
+            },
+        ]);
+        const result = await listSources({ entity: ENTITY, channel: "meeting" });
+        expect(result.entries).toHaveLength(1);
+        expect(result.entries[0].sourceId).toBe("abc");
+        expect(result.entries[0].channel).toBe("meeting");
+        expect(result.entries[0].key).toBe("sources/meeting/abc.md");
+        expect(result.entries[0].size).toBeGreaterThan(0);
+        expect(result.entries[0].frontmatter).toBeUndefined();
+        expect(result.nextToken).toBeUndefined();
+    });
+    it("pagination: returns nextToken and accepts it on the next call", async () => {
+        const objects = Array.from({ length: 5 }, (_, i) => ({
+            key: `sources/meeting/m${i}.md`,
+            content: MEETING_MD,
+            lastModified: new Date("2026-03-15T14:00:00Z"),
+        }));
+        installStub(objects);
+        const page1 = await listSources({
+            entity: ENTITY,
+            channel: "meeting",
+            limit: 2,
+        });
+        expect(page1.entries).toHaveLength(2);
+        expect(page1.entries.map((e) => e.sourceId)).toEqual(["m0", "m1"]);
+        expect(page1.nextToken).toBe("2");
+        const page2 = await listSources({
+            entity: ENTITY,
+            channel: "meeting",
+            limit: 2,
+            continuationToken: page1.nextToken,
+        });
+        expect(page2.entries.map((e) => e.sourceId)).toEqual(["m2", "m3"]);
+        expect(page2.nextToken).toBe("4");
+        const page3 = await listSources({
+            entity: ENTITY,
+            channel: "meeting",
+            limit: 2,
+            continuationToken: page2.nextToken,
+        });
+        expect(page3.entries.map((e) => e.sourceId)).toEqual(["m4"]);
+        expect(page3.nextToken).toBeUndefined();
+    });
+    it("includeFrontmatter:true fetches each object and parses YAML", async () => {
+        const observed = installStub([
+            {
+                key: "sources/meeting/abc.md",
+                content: MEETING_MD,
+                lastModified: new Date("2026-03-15T14:00:00Z"),
+            },
+        ]);
+        const result = await listSources({
+            entity: ENTITY,
+            channel: "meeting",
+            includeFrontmatter: true,
+        });
+        expect(result.entries).toHaveLength(1);
+        expect(result.entries[0].frontmatter).toEqual({
+            source_id: "abc",
+            source_type: "meeting",
+            channel: "meeting",
+            title: "Hello",
+        });
+        // 1 list + 1 get for the single entry.
+        expect(observed.commands.filter((c) => c instanceof GetObjectCommand)).toHaveLength(1);
+    });
+    it("includeFrontmatter:false (default) does not perform GETs", async () => {
+        const observed = installStub([
+            {
+                key: "sources/meeting/abc.md",
+                content: MEETING_MD,
+                lastModified: new Date(),
+            },
+        ]);
+        await listSources({ entity: ENTITY, channel: "meeting" });
+        expect(observed.commands.filter((c) => c instanceof GetObjectCommand)).toHaveLength(0);
+    });
+    it("uses the correct prefix per channel", async () => {
+        const observed = installStub([]);
+        await listSources({ entity: ENTITY, channel: "slack" });
+        const listCmd = observed.commands[0];
+        expect(listCmd.input.Prefix).toBe("sources/slack/");
+    });
+    it("rejects an invalid channel via assertSourceChannel BEFORE any S3 call", async () => {
+        const observed = installStub([]);
+        await expect(listSources({
+            entity: ENTITY,
+            // @ts-expect-error — invalid channel intentional for negative test
+            channel: "pigeon",
+        })).rejects.toBeInstanceOf(InvalidSourceChannelError);
+        expect(observed.commands).toHaveLength(0);
+    });
+});
+//# sourceMappingURL=list.test.js.map

package/dist/sources/list.test.js.map

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

package/dist/sources/parse.d.ts

@@ -0,0 +1,18 @@
+/**
+ * YAML frontmatter parsing for source markdown documents.
+ *
+ * Format: a leading `---\n` block terminated by `\n---\n`, followed by the body.
+ * Tolerates LF and CRLF. Returns `{ frontmatter: null, body }` when no
+ * frontmatter block is present.
+ */
+export interface ParsedMarkdown {
+    frontmatter: Record<string, unknown> | null;
+    body: string;
+}
+export declare function parseMarkdown(content: string): ParsedMarkdown;
+/**
+ * Convenience: parse only the frontmatter (used by listSources includeFrontmatter
+ * where we don't need the body).
+ */
+export declare function parseFrontmatter(content: string): Record<string, unknown> | null;
+//# sourceMappingURL=parse.d.ts.map

package/dist/sources/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/sources/parse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;CACd;AAID,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAiB7D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEhF"}

package/dist/sources/parse.js

@@ -0,0 +1,35 @@
+/**
+ * YAML frontmatter parsing for source markdown documents.
+ *
+ * Format: a leading `---\n` block terminated by `\n---\n`, followed by the body.
+ * Tolerates LF and CRLF. Returns `{ frontmatter: null, body }` when no
+ * frontmatter block is present.
+ */
+import { load as yamlLoad } from "js-yaml";
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+export function parseMarkdown(content) {
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match) {
+        return { frontmatter: null, body: content };
+    }
+    const [, yamlBlock, body] = match;
+    let frontmatter;
+    try {
+        const loaded = yamlLoad(yamlBlock);
+        frontmatter = loaded && typeof loaded === "object" && !Array.isArray(loaded)
+            ? loaded
+            : null;
+    }
+    catch {
+        frontmatter = null;
+    }
+    return { frontmatter, body };
+}
+/**
+ * Convenience: parse only the frontmatter (used by listSources includeFrontmatter
+ * where we don't need the body).
+ */
+export function parseFrontmatter(content) {
+    return parseMarkdown(content).frontmatter;
+}
+//# sourceMappingURL=parse.js.map

package/dist/sources/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/sources/parse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,SAAS,CAAC;AAO3C,MAAM,cAAc,GAAG,6CAA6C,CAAC;AAErE,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC9C,CAAC;IAED,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC;IAClC,IAAI,WAA2C,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;QACnC,WAAW,GAAG,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAC1E,CAAC,CAAE,MAAkC;YACrC,CAAC,CAAC,IAAI,CAAC;IACX,CAAC;IAAC,MAAM,CAAC;QACP,WAAW,GAAG,IAAI,CAAC;IACrB,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC;AAC5C,CAAC"}

package/dist/sources/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Public types for the sources read surface.
+ *
+ * Mirrors the sources-pipeline write path so a meeting source written by
+ * hq-pro is readable through this layer without translation.
+ */
+import type { SourceChannel } from "../schemas/source-channels.js";
+/**
+ * Lightweight summary returned by listSources(). `frontmatter` is only
+ * populated when the caller passes `includeFrontmatter: true`.
+ */
+export interface SourceSummary {
+    /** Stable ID derived from the object key (filename minus `.md`/`.raw.json`). */
+    sourceId: string;
+    channel: SourceChannel;
+    /** Full S3 object key (e.g. "sources/meeting/abc.md"). */
+    key: string;
+    lastModified: Date;
+    size: number;
+    /** Parsed YAML frontmatter — only present when listSources(includeFrontmatter:true). */
+    frontmatter?: Record<string, unknown>;
+}
+/**
+ * Full source document returned by getSource(). `frontmatter` is `null` if
+ * the document was malformed (no `---` delimiters) — body still contains the
+ * raw payload in that case so callers can fall back.
+ */
+export interface SourceDocument {
+    key: string;
+    /** Parsed YAML frontmatter, or `null` if the document had no frontmatter block. */
+    frontmatter: Record<string, unknown> | null;
+    /** Markdown body (everything after the closing `---`). */
+    body: string;
+    /** Sibling `.raw.json` payload, only present when getSource(includeRaw:true). */
+    raw?: unknown;
+}
+/**
+ * Listing options for listSources().
+ */
+export interface ListSourcesOptions {
+    entity: import("../types.js").EntityContext;
+    channel: SourceChannel;
+    /** Max keys per page; defaults to S3 default (1000). */
+    limit?: number;
+    /** Opaque continuation token returned by a prior page. */
+    continuationToken?: string;
+    /** When true, fetches+parses each entry's frontmatter (extra GETs). */
+    includeFrontmatter?: boolean;
+}
+export interface ListSourcesResult {
+    entries: SourceSummary[];
+    /** Present when the result was truncated; pass back as continuationToken. */
+    nextToken?: string;
+}
+export interface GetSourceOptions {
+    entity: import("../types.js").EntityContext;
+    channel: SourceChannel;
+    sourceId: string;
+    /** When true, also fetches the `.raw.json` sibling. */
+    includeRaw?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sources/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sources/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,aAAa,CAAC;IACvB,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,aAAa,EAAE,aAAa,CAAC;IAC5C,OAAO,EAAE,aAAa,CAAC;IACvB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,aAAa,EAAE,aAAa,CAAC;IAC5C,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB"}

package/dist/sources/types.js

@@ -0,0 +1,8 @@
+/**
+ * Public types for the sources read surface.
+ *
+ * Mirrors the sources-pipeline write path so a meeting source written by
+ * hq-pro is readable through this layer without translation.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/sources/types.js.map

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

package/dist/telemetry.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Usage telemetry collector — TypeScript port of the Tauri Rust collector that
+ * used to live at `hq-workspace/apps/hq-sync/src-tauri/src/commands/telemetry.rs`.
+ *
+ * Why it moved: the Rust copy only ran inside the macOS menubar app. By moving
+ * the logic into `@indigoai-us/hq-cloud`, every consumer of the package
+ * (`hq-sync-runner`, `hq-cli`, mobile wrappers) emits telemetry uniformly.
+ *
+ * What it does: after each successful sync (`all-complete` arm of
+ * `bin/sync-runner.ts`), walks `~/.claude/projects/**\/*.jsonl`, diffs each
+ * file against a persisted byte-offset cursor at `~/.hq/telemetry-cursor.json`,
+ * sanitizes new rows through a tight allowlist that matches the server's
+ * KEEP_FIELDS set in `apps/hq-pro/src/vault-service/handlers/usage.ts`,
+ * batches into ≤1 MiB POST bodies, and ships them to `/v1/usage`.
+ *
+ * Trust model: the caller's `personUid` is resolved on the server from the
+ * Cognito JWT — never from the body. `sanitizeRow` strips prompt bodies,
+ * thinking content, tool inputs/outputs, and any nested `message` object so
+ * the wire payload contains only token-accounting fields.
+ *
+ * Errors are swallowed by design — telemetry must never abort or delay a
+ * sync. The cursor is only advanced for batches the server 2xx'd, so a
+ * transient outage retries automatically on the next sync.
+ */
+import type { TelemetryOptInResponse, UsageBatch, UsageIngestResult } from "./vault-client.js";
+/**
+ * Minimal subset of `VaultClient` the collector needs. Declared as an
+ * interface so tests can inject a stub without spinning up a fetch mock.
+ * The real `VaultClient` from `./vault-client.js` satisfies this structurally.
+ */
+export interface TelemetryClientSurface {
+    getTelemetryOptIn(): Promise<TelemetryOptInResponse>;
+    postUsage(batch: UsageBatch): Promise<UsageIngestResult>;
+}
+export interface CollectTelemetryOptions {
+    client: TelemetryClientSurface;
+    /** Stable per-machine id. The Tauri menubar reads this from `~/.hq/menubar.json`; the runner can pass it through or generate one once and cache. */
+    machineId: string;
+    /** Version of the wrapping caller (menubar app, CLI, etc.). Reaches CloudWatch metrics as the `installerVersion` dimension. */
+    installerVersion: string;
+    /** Override `~/.claude/projects` for tests. */
+    claudeProjectsRoot?: string;
+    /** Override `~/.hq/telemetry-cursor.json` for tests. */
+    cursorPath?: string;
+    /** Override `~/.hq/menubar.json` (the offline opt-in fallback) for tests. */
+    menubarPath?: string;
+    /** Diagnostic sink. No-op by default. */
+    log?: (msg: string) => void;
+}
+export interface CollectTelemetryResult {
+    /** Whether the opt-in check resolved to true (either server-side or via the menubar fallback). When false, nothing else ran. */
+    enabled: boolean;
+    /** Source for the `enabled` decision — useful for diagnosing missing-events reports. */
+    optInSource: "server" | "menubar-fallback" | "skipped";
+    /** How many `.jsonl` files we considered (before the cursor diff). */
+    filesScanned: number;
+    /** Total events successfully POSTed across all batches. */
+    eventsSent: number;
+    /** Number of `POST /v1/usage` requests made. */
+    batchesSent: number;
+}
+/**
+ * Build an outgoing event row matching the server's KEEP allowlist.
+ *
+ * Two transforms:
+ *   1. Top-level fields are copied straight through (string identity).
+ *   2. `message.model` and `message.usage.{input_tokens, output_tokens,
+ *      cache_creation_input_tokens, cache_read_input_tokens}` are promoted to
+ *      camelCase top-level fields. The original `message` object — which
+ *      carries prompt/response text, thinking, and tool data — is dropped.
+ *
+ * Returns `null` when the input isn't an object. Empty results (e.g. a row
+ * with no recognised fields) are still returned as `{}` and emitted; the
+ * server accepts empty rows and they're useful as a "Claude Code was run at
+ * this time" heartbeat.
+ */
+export declare function sanitizeRow(row: unknown): Record<string, unknown> | null;
+/**
+ * Scan, sanitize, and POST any new Claude Code session rows.
+ *
+ * Fire-and-forget from the caller's perspective: errors are caught internally
+ * and surfaced only via `log`. The returned summary lets observers (e.g.
+ * sync-runner) decide whether to record a "telemetry attempted" breadcrumb,
+ * but no consumer is expected to react to it.
+ */
+export declare function collectAndSendTelemetry(opts: CollectTelemetryOptions): Promise<CollectTelemetryResult>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,KAAK,EACV,sBAAsB,EACtB,UAAU,EACV,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAI3B;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,iBAAiB,IAAI,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACrD,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,oJAAoJ;IACpJ,SAAS,EAAE,MAAM,CAAC;IAClB,+HAA+H;IAC/H,gBAAgB,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,gIAAgI;IAChI,OAAO,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,WAAW,EAAE,QAAQ,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACvD,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;CACrB;AAkED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CA8BxE;AA6DD;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,sBAAsB,CAAC,CAmLjC"}