@indigoai-us/hq-cli 5.345.190 → 5.345.193

package/dist/lib/flag-registry.d.ts

@@ -6,7 +6,7 @@
  * keep a short-lived, offline CLI alive until the client's network deadline.
  */
 import { type WorkerOptions } from "node:worker_threads";
-import { createFlagClient, type FlagClient, type FlagLookupOptions, type FlagSnapshot } from "@indigoai-us/hq-flags-client";
+import { createFlagClient, type FlagClient, type FlagLookupOptions, type FlagResolution, type FlagSnapshot } from "@indigoai-us/hq-flags-client";
 type FlagRegistrySentry = Pick<typeof import("@sentry/node"), "captureException" | "withScope">;
 export { resolveProcessFlagCompanyContext } from "./process-flag-company-context.js";
 export type { ProcessFlagCompanyContext } from "./process-flag-company-context.js";
@@ -66,6 +66,18 @@ export declare function refreshFlagRegistrySnapshot(timeoutMs?: number): Promise
 export declare function resolveFlagGate(reader: FlagReader | null | undefined, flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean, env?: NodeJS.ProcessEnv): boolean;
 /** Resolve one explicit company's flag without relying on process-wide binding. */
 export declare function resolveCompanyFlagGate(companyUid: string, idToken: string, flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean, dependencies?: CompanyFlagGateDependencies): Promise<boolean>;
+/**
+ * Read one explicit company's flag and say whether the registry answered.
+ *
+ * Returns the evaluator's resolution when the registry snapshot loaded (an
+ * absent row resolves to `lookup.fallback`, source "fallback"), a
+ * "local-override" resolution when the process sets one, and null when the
+ * registry could not be read: no company uid or token, a client error, a
+ * timeout, or a failed load. Callers that keep a last-known value (ingest
+ * kill switches) use the null to tell an unreadable registry from an answer.
+ * Bounded by the client's request timeout, like `resolveCompanyFlagGate`.
+ */
+export declare function readCompanyFlag(companyUid: string, idToken: string, flagKey: string, lookup: FlagLookupOptions, dependencies?: CompanyFlagGateDependencies): Promise<FlagResolution | null>;
 /** Resolve a process gate against the shared snapshot reader, when configured. */
 export declare function resolveProcessFlagGate(flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean, companyUid?: string, options?: {
     acceptStaleSnapshot?: boolean;

package/dist/lib/flag-registry.js

@@ -354,6 +354,52 @@ export async function resolveCompanyFlagGate(companyUid, idToken, flagKey, looku
         client?.close();
     }
 }
+/**
+ * Read one explicit company's flag and say whether the registry answered.
+ *
+ * Returns the evaluator's resolution when the registry snapshot loaded (an
+ * absent row resolves to `lookup.fallback`, source "fallback"), a
+ * "local-override" resolution when the process sets one, and null when the
+ * registry could not be read: no company uid or token, a client error, a
+ * timeout, or a failed load. Callers that keep a last-known value (ingest
+ * kill switches) use the null to tell an unreadable registry from an answer.
+ * Bounded by the client's request timeout, like `resolveCompanyFlagGate`.
+ */
+export async function readCompanyFlag(companyUid, idToken, flagKey, lookup, dependencies = {}) {
+    const localOverride = processLocalOverride(flagKey);
+    if (localOverride !== null)
+        return { value: localOverride, source: "local-override" };
+    const targetCompanyUid = normalizedCompanyUid(companyUid);
+    if (!targetCompanyUid || idToken.trim() === "")
+        return null;
+    let client;
+    try {
+        client = (dependencies.createClient ?? createFlagClient)({
+            endpoint: resolveFlagRegistryEndpoint(dependencies.endpoint, process.env),
+            getToken: () => idToken,
+            companyUid: targetCompanyUid,
+            refreshIntervalMs: 0,
+            requestTimeoutMs: dependencies.requestTimeoutMs ?? 1_200,
+            onError: (error) => {
+                const errorClass = error instanceof Error ? error.name : "unknown";
+                console.error(`hq: Could not read a company flag (${errorClass}).`);
+            },
+        });
+        await client.ready();
+        // ready() resolves after a failed load too; no snapshot means no answer.
+        if (client.snapshot() === null)
+            return null;
+        return client.explain(flagKey, lookup);
+    }
+    catch (error) {
+        const errorClass = error instanceof Error ? error.name : "unknown";
+        console.error(`hq: Could not read a company flag (${errorClass}).`);
+        return null;
+    }
+    finally {
+        client?.close();
+    }
+}
 /** Resolve a process gate against the shared snapshot reader, when configured. */
 export function resolveProcessFlagGate(flagKey, lookup, legacyFallback, companyUid, options = {}) {
     const defaultOnKillSwitch = options.killSwitchWithoutCompany === true;

package/dist/lib/hot-channels/adapters/attio.d.ts

@@ -4,8 +4,10 @@
  * The Attio webhook receiver in hq-pro-agents
  * (`src/sources/inbound/attio-events.ts`) is the push half: it lands one
  * document per delivery in the company vault under `sources/attio/`, with
- * `event_key: attio:{Idempotency-Key}` in the frontmatter and the webhook
- * payload in the `.raw.json` sidecar. This adapter is the drain half, a poll
+ * `event_key: attio:{deliveryHash}` in the frontmatter, where deliveryHash is
+ * `sha256hex(Idempotency-Key + "\n" + rawBody)` (the raw key is kept in a
+ * separate `idempotency_key` field), and the webhook payload in the
+ * `.raw.json` sidecar. This adapter is the drain half, a poll
  * adapter over that folder, the same shape as Slack (US-006). The cursor is
  * the newest `ingested_at` it has read.
  *
@@ -31,6 +33,50 @@
  * `payload_ref` names the landed source document. No payload is copied: the
  * `.raw.json` sidecar holds the source frontmatter and why the delivery
  * matched.
+ *
+ * US-010 adds a gateway pull as the catch-up path alongside the drain, for
+ * changes whose webhook never landed. Once the drain has no more pages, each
+ * fetch asks the gateway for records (`list-records`, one call per object in
+ * `pullObjects`, filtered `created_at > watermark`, sorted ascending, limit
+ * 50) and notes (`search-notes-by-metadata` with `created_at_gt`) newer than
+ * that source's watermark. A pulled item is kept on the same rule as a
+ * delivery: the person created it or owns its record. The Attio gateway has
+ * no updated-at filter on records, so record updates still come from the
+ * webhook drain; the pull catches records and notes that were created.
+ *
+ * Event keys follow the US-008 shape `attio:{recordId}:{eventId}`, built from
+ * Attio ids both paths have, so a create the webhook delivered and the pull
+ * found lands once:
+ *   - a create (a delivery holding one `record.created` or `note.created`
+ *     event, or a pulled record or note) is `attio:{record_id}:record.created`
+ *     or `attio:{note_id}:note.created`;
+ *   - every other delivery is `attio:{subjectId}:{deliveryHash}`, where the
+ *     subject is the note, comment, record or entry the first event names, so
+ *     two updates to one record stay two items.
+ *
+ * The cursor is JSON `{ drain, pull }`: `drain` is the newest `ingested_at`
+ * read, and `pull` maps `records:{object}` and `notes` to the newest
+ * `created_at` read. A plain ISO string from before US-010 reads as `drain`.
+ *
+ * Upgrading from the drain before US-010 (re-review C): that drain keyed every
+ * delivery `attio:{deliveryHash}:{event_type}`, and a plain ISO cursor gives
+ * the pull no watermark, so the first pull reads the whole catch-up window.
+ * Landing dedupes on the event key alone (the landed document's path), so
+ * nothing the old drain landed may come back under a new key:
+ *   - the drain keeps the old key for a delivery whose document under the old
+ *     key is already landed (the deliveries at the old cursor are re-read);
+ *   - the pull gives a create the old key of the landed delivery that carried
+ *     it, so landing reports a duplicate.
+ * A create the old drain never landed (its webhook was lost, or it is newer
+ * than the old cursor) has no document under an old key and lands under the
+ * new one. The pull watermark is not seeded from the old cursor, so those
+ * lost creates are not skipped.
+ *
+ * Rate limits: every gateway call retries a 429 with backoff (Retry-After
+ * when Attio sends it), at most ATTIO_MAX_RETRIES times, and one fetch makes
+ * at most ATTIO_MAX_REQUESTS_PER_FETCH calls. A persistent 429 or the cap
+ * throws AttioRateLimitedError before a cursor is returned, so the watermark
+ * stays where it was.
  */
 import { type PollHotChannelAdapter } from "../contract.js";
 export declare const ATTIO_ADAPTER_ID = "attio";
@@ -42,6 +88,15 @@ export declare const ATTIO_COMMENT_EVENT = "attio.comment";
 export declare const ATTIO_NOTE_EVENT = "attio.note";
 export declare const ATTIO_LIST_MEMBERS_TOOL = "list-workspace-members";
 export declare const ATTIO_GET_RECORDS_TOOL = "get-records-by-ids";
+export declare const ATTIO_LIST_RECORDS_TOOL = "list-records";
+export declare const ATTIO_SEARCH_NOTES_TOOL = "search-notes-by-metadata";
+/** Records per `list-records` call; the Attio policy caps it at 50. */
+export declare const ATTIO_PULL_LIMIT = 50;
+/** Objects the catch-up pull lists by default. */
+export declare const ATTIO_DEFAULT_PULL_OBJECTS: readonly string[];
+export declare const ATTIO_MAX_RETRIES = 3;
+/** Gateway calls one fetch may make, retries included. */
+export declare const ATTIO_MAX_REQUESTS_PER_FETCH = 200;
 /**
  * Suggestion rule data: Attio is suggested when the person owns a record with
  * activity in the last 14 days. The contract's `owned-by-me` rule has no
@@ -62,6 +117,24 @@ export interface AttioAdapterOptions {
     memberIds?: readonly string[];
     /** Deliveries newer than the cursor per page. Default 100. */
     pageSize?: number;
+    /** Objects the catch-up pull lists. Default companies, people, deals. Empty turns the record pull off. */
+    pullObjects?: readonly string[];
+    /** Waits between rate-limit retries. Tests pass a fake. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Attio kept answering 429 after every retry, or the run hit its request cap; the cursor stays put. */
+export declare class AttioRateLimitedError extends Error {
+    readonly retryAfterMs: number | null;
+    readonly code = "rate_limited";
+    readonly status = 429;
+    constructor(retryAfterMs: number | null);
+}
+/** The adapter's cursor: see the file comment. */
+export interface AttioCursor {
+    drain: string | null;
+    pull: Record<string, string>;
 }
+/** Parse a stored cursor. A plain ISO string (before US-010) is the drain cursor. */
+export declare function parseAttioCursor(raw: string | null): AttioCursor;
 export declare function createAttioAdapter(options: AttioAdapterOptions): PollHotChannelAdapter;
 //# sourceMappingURL=attio.d.ts.map