@leadpoet/client 0.1.4 → 0.1.5

package/types/shared/assistant.d.ts

@@ -0,0 +1,238 @@
+/**
+ * The in-app assistant's wire contract, shared by its server routes and the
+ * dashboard panel. The assistant reads the workspace, writes documents and
+ * proposes actions. An action runs only when the user presses Run on its
+ * card, sends included.
+ */
+/** Screens the assistant may link to. Anything else renders as plain text. */
+export declare const ASSISTANT_LINKS: {
+    readonly requests: "/dashboard/lead-engine";
+    readonly pipeline: "/dashboard/pipeline";
+    readonly signals: "/dashboard/pipeline?entity=signals";
+    readonly review: "/dashboard/outreach?inbox=review";
+    readonly replies: "/dashboard/outreach?inbox=conversations";
+    readonly queued: "/dashboard/outreach?inbox=queued";
+    readonly campaigns: "/dashboard/outreach/campaigns";
+    /** Outreach settings, Products & writing, open at the saved offer, proof and writing rules. */
+    readonly writing: "/dashboard/outreach/campaigns?settings=writing";
+    readonly icps: "/dashboard/account?section=saved-icps";
+    readonly analytics: "/dashboard/outreach/analytics";
+    readonly network: "/dashboard/outreach/network";
+    readonly senders: "/dashboard/account?section=integrations";
+    readonly playbook: "/dashboard/account?section=playbook";
+    readonly billing: "/dashboard/account?section=billing";
+    readonly scheduled: "/dashboard?agent=scheduled";
+    readonly memory: "/dashboard?agent=memory";
+};
+/**
+ * One account opened on the pipeline, on its ICP's board when known. With a
+ * contact (and an ICP), it opens on that contact's notes and follow-ups.
+ */
+export declare function assistantAccountLink(cardId: string, icpId?: string | null, contactId?: string | null): string;
+/**
+ * The in-app path a model-written link may open, or null. Only the screens in
+ * ASSISTANT_LINKS qualify, with a plain query string; other hosts, schemes and
+ * paths never become links.
+ */
+export declare function safeAssistantHref(href: string): string | null;
+/** Source links one answer may open, at most; reads past it add none. */
+export declare const ASSISTANT_SOURCE_LIMIT = 200;
+/**
+ * A source address Leadpoet stored, as the agent may link it: https only,
+ * with no sign-in part, as stored, or null. Signals keeps only such links.
+ */
+export declare function assistantSourceUrl(value: unknown): string | null;
+/**
+ * The outside address a model-written link may open, or null: only an exact
+ * copy of a source link that a read showed the agent in this answer. A model
+ * cannot add one, and one character off stays plain text.
+ */
+export declare function verifiedSourceHref(href: string, sources: ReadonlySet<string> | undefined): string | null;
+/** A Markdown link, and a bare web address, as model answers write them. */
+export declare const ASSISTANT_MARKDOWN_LINK: RegExp;
+export declare const ASSISTANT_BARE_ADDRESS: RegExp;
+/**
+ * An answer for a place outside Leadpoet, such as Slack, with only Leadpoet's
+ * own links, as the panel shows it: a link to one of its screens becomes a
+ * full link at `origin`; any other link keeps its words and loses its
+ * address; a bare address, often quoted from a prospect, is left out.
+ */
+export declare function assistantOwnLinks(markdown: string, origin: string): string;
+/** Screens the assistant can be told the user has open, with how the model reads each. */
+export declare const ASSISTANT_SCREENS: {
+    readonly requests: "the Lead engine (lead requests)";
+    readonly pipeline: "the pipeline board";
+    readonly review: "Outreach review (drafts waiting for approval)";
+    readonly replies: "Outreach conversations (replies)";
+    readonly queued: "Outreach queued messages";
+    readonly outreach: "Outreach";
+    readonly campaigns: "the campaign list";
+    readonly analytics: "Outreach analytics";
+    readonly network: "the LinkedIn network";
+    readonly senders: "sending account settings";
+    readonly settings: "account settings";
+};
+export type AssistantScreen = keyof typeof ASSISTANT_SCREENS;
+/** What the user has open when they ask; only IDs and fixed screen names, never page text. */
+export type AssistantPage = {
+    screen: AssistantScreen;
+    accountId?: string;
+};
+/** The screen a dashboard URL shows, or null for any other page. */
+export declare function assistantPage(pathname: string, search: string): AssistantPage | null;
+export declare const ASSISTANT_LIMITS: {
+    /** Turns sent per request; older turns are dropped first. */
+    readonly messages: 24;
+    readonly messageChars: 4000;
+    /** Answers can be longer than questions: a one-pager runs past 4,000 characters. */
+    readonly answerChars: 12000;
+    /** UTF-8 bytes of all turns sent per request; older turns drop first. Keeps a request under the 100 KB body limit and bounds its cost. */
+    readonly historyBytes: 80000;
+    /** One confirmed change, server side; the browser waits a little longer. */
+    readonly actionMs: 30000;
+    /** One answer, every model call and read included; the browser waits a little longer. */
+    readonly turnMs: 120000;
+};
+export declare const ASSISTANT_TIMEOUT_MESSAGE = "This answer took too long. Try a narrower question.";
+export type AssistantRole = "user" | "assistant";
+export type AssistantMessage = {
+    role: AssistantRole;
+    content: string;
+};
+/**
+ * What running an action does, from the operation's reviewed metadata.
+ * "send" is Review's server-built approve card and the listed send cards.
+ */
+export declare const ASSISTANT_ACTION_EFFECTS: readonly ["create", "modify", "spend", "send"];
+export type AssistantActionEffect = (typeof ASSISTANT_ACTION_EFFECTS)[number];
+/** An action the assistant proposes. Nothing runs until the user presses Run. */
+export type AssistantAction = {
+    operation: string;
+    title: string;
+    effect: AssistantActionEffect;
+    /** The model's one-line description; the details below come from the arguments themselves. */
+    summary: string;
+    details: Array<{
+        label: string;
+        value: string;
+    }>;
+    arguments: Record<string, unknown>;
+    /** A send card's plain statement of what Run does, from the server. */
+    consequence?: string;
+    /** It can't be undone: Run asks once more, and the server refuses a run without that confirmation. */
+    irreversible?: true;
+    /** A credit spend's exact charge, priced by the server; the route charges this or refuses. */
+    credits?: number;
+    /** The server's signed mark of the turn or run that proposed a spend; the browser passes it back unread. */
+    origin?: string;
+    /** A send card's digest of what it showed, returned on Run so a changed message doesn't go out under it. */
+    facts?: string;
+    /** Slack only: the id its saved card takes, chosen before it was proposed so a preview it saved and its Run share one key. */
+    cardId?: string;
+};
+export type AssistantActionRun = {
+    operation: string;
+    arguments: Record<string, unknown>;
+    key: string;
+    credits?: number;
+    origin?: string;
+    facts?: string;
+    confirmed?: true;
+};
+/** What a card's Run sends back: its arguments, and a spend's price and origin as the server gave them. */
+export declare function actionRun(action: AssistantAction, key: string, confirmed?: boolean): AssistantActionRun;
+/** unknown: no answer came back, so the change may have been made; the user checks before running it again. */
+/** A run's outcome. `undo` is a card the server built from what the run returned, such as a qualification's receipt, so the user can reverse it. */
+export type AssistantActionResult = {
+    ok: true;
+    message: string;
+    href?: string;
+    undo?: AssistantAction;
+} | {
+    ok: false;
+    message: string;
+    unknown?: true;
+};
+export declare const ASSISTANT_DOCUMENT_KINDS: readonly ["one_pager", "deck", "brief", "email"];
+export type AssistantDocumentKind = (typeof ASSISTANT_DOCUMENT_KINDS)[number];
+/** A document the assistant wrote: a deck shows one section per slide, the rest as a page. */
+export type AssistantDocument = {
+    kind: AssistantDocumentKind;
+    title: string;
+    subtitle?: string;
+    sections: Array<{
+        heading: string;
+        body: string;
+    }>;
+};
+export declare const ASSISTANT_DOCUMENT_LIMITS: {
+    readonly title: 120;
+    readonly subtitle: 200;
+    readonly heading: 120;
+    readonly body: 4000;
+    readonly sections: 14;
+};
+/**
+ * Server-sent events on POST /api/assistant/chat. Text arrives as deltas; a
+ * step starts a read and discards the text before it. Actions and documents
+ * arrive as the model makes them; sources arrive with the read that showed
+ * them, before any words can cite them. The turn ends with one message or error.
+ */
+export type AssistantChatEvent = {
+    type: "step";
+    label: string;
+} | {
+    type: "delta";
+    text: string;
+} | {
+    type: "action";
+    action: AssistantAction;
+} | {
+    type: "document";
+    document: AssistantDocument;
+}
+/** Stored source links a read showed the agent; only these outside links open. */
+ | {
+    type: "sources";
+    urls: string[];
+} | {
+    type: "message";
+    content: string;
+} | {
+    type: "error";
+    code: AssistantErrorCode;
+    message: string;
+};
+export type AssistantErrorCode = "unavailable" | "rate_limited" | "daily_limit" | "ai_actions_exhausted" | "ai_actions_unavailable" | "failed";
+/** Where the workspace is on the way to its first send. */
+export type AssistantSetupStep = "request" | "delivery" | "sender" | "campaign" | "send" | "done";
+export type AssistantTodayItem = {
+    id: string;
+    kind: "setup" | "reply" | "review" | "sender" | "signal" | "request" | "campaign" | "task";
+    title: string;
+    detail?: string;
+    href: string;
+    action: string;
+};
+/** Accounts shown under "Work these first". */
+export declare const ASSISTANT_FOCUS_LIMIT = 5;
+/** One pipeline account to work now, with every reason it is listed. */
+export type AssistantFocusAccount = {
+    id: string;
+    name: string;
+    /** Plain reasons, strongest first, such as "Dana Lee asked a question · 2 d ago". */
+    reasons: string[];
+    href: string;
+};
+export type AssistantToday = {
+    setup: AssistantSetupStep | null;
+    items: AssistantTodayItem[];
+    /** Sources that could not be read; their items are missing, not zero. */
+    unavailable: string[];
+};
+/** GET /api/assistant/focus: "Work these first". */
+export type AssistantFocus = {
+    accounts: AssistantFocusAccount[];
+    /** Sources that could not be read, so the ranking may miss accounts. */
+    unavailable: string[];
+};

package/types/shared/employee-count.d.ts

@@ -0,0 +1,90 @@
+/** Inclusive employee-count bands shared by imports, display, and new filters. */
+export declare const EMPLOYEE_COUNT_BANDS: readonly [{
+    readonly value: "1_10";
+    readonly label: "1-10";
+    readonly min: 1;
+    readonly max: 10;
+}, {
+    readonly value: "11_50";
+    readonly label: "11-50";
+    readonly min: 11;
+    readonly max: 50;
+}, {
+    readonly value: "51_200";
+    readonly label: "51-200";
+    readonly min: 51;
+    readonly max: 200;
+}, {
+    readonly value: "201_500";
+    readonly label: "201-500";
+    readonly min: 201;
+    readonly max: 500;
+}, {
+    readonly value: "501_1000";
+    readonly label: "501-1,000";
+    readonly min: 501;
+    readonly max: 1000;
+}, {
+    readonly value: "1001_5000";
+    readonly label: "1,001-5,000";
+    readonly min: 1001;
+    readonly max: 5000;
+}, {
+    readonly value: "5001_10000";
+    readonly label: "5,001-10,000";
+    readonly min: 5001;
+    readonly max: 10000;
+}, {
+    readonly value: "10001_plus";
+    readonly label: "10,001+";
+    readonly min: 10001;
+    readonly max: number;
+}];
+/** Parse reported counts without guessing a midpoint or accepting partial text. */
+export declare function parseEmployeeCount(raw: unknown): {
+    min: number;
+    max: number;
+} | null;
+export declare function employeeCountBand(raw: unknown): {
+    readonly value: "1_10";
+    readonly label: "1-10";
+    readonly min: 1;
+    readonly max: 10;
+} | {
+    readonly value: "11_50";
+    readonly label: "11-50";
+    readonly min: 11;
+    readonly max: 50;
+} | {
+    readonly value: "51_200";
+    readonly label: "51-200";
+    readonly min: 51;
+    readonly max: 200;
+} | {
+    readonly value: "201_500";
+    readonly label: "201-500";
+    readonly min: 201;
+    readonly max: 500;
+} | {
+    readonly value: "501_1000";
+    readonly label: "501-1,000";
+    readonly min: 501;
+    readonly max: 1000;
+} | {
+    readonly value: "1001_5000";
+    readonly label: "1,001-5,000";
+    readonly min: 1001;
+    readonly max: 5000;
+} | {
+    readonly value: "5001_10000";
+    readonly label: "5,001-10,000";
+    readonly min: 5001;
+    readonly max: 10000;
+} | {
+    readonly value: "10001_plus";
+    readonly label: "10,001+";
+    readonly min: 10001;
+    readonly max: number;
+} | undefined;
+/** Empty means absent. Unknown or unsupported cross-band values stay blank. */
+export declare function normalizeEmployeeCount(raw: unknown): string;

package/types/shared/gtm-context.d.ts

@@ -0,0 +1,233 @@
+import { z } from "zod";
+/**
+ * GTM context: what this workspace knows about how it sells, selected for one
+ * task. One builder serves the in-app agent, Slack, phone and MCP. Each caller
+ * supplies only how to run a workspace read as the user, so auth, team access
+ * and scopes stay those of the read itself.
+ *
+ * It reads the outreach profile, one published ICP, that ICP's fit insights
+ * and the user's saved memories, then keeps what matters most for the task
+ * within a character budget. An ICP separated from its Products keeps its
+ * problems, objections, signals and writing guidance on each Product's
+ * connection, so the connected Product is read too. It is the workspace's context, not a campaign's:
+ * a campaign can write with its own product, ICP version and guidance.
+ * Selection follows what made task-aware context work in evaluations:
+ * whole items only (a claim keeps its customer and dates), every
+ * relevant section represented before any one section fills up, and what was
+ * left out counted, never hidden.
+ *
+ * Guardrails are always listed in full, outside the budget. If any source of
+ * them could not be read, or several ICPs (or an ICP's several Products) are
+ * published and none was named, `guardrails_complete` is false, so nothing prospect-facing is written
+ * against an unknown rule. Complete covers the outreach profile and the ICP
+ * read, never a campaign's own rules. Proof is listed only when it is approved and
+ * current, as campaign launch requires. A section with nothing saved is
+ * "missing" with the screen that adds it; a read that failed or is not allowed
+ * is "unavailable", never "missing".
+ */
+export declare const GTM_CONTEXT_TASKS: readonly ["messaging", "targeting", "objections", "call_prep", "overview"];
+export type GtmContextTask = (typeof GTM_CONTEXT_TASKS)[number];
+export declare const GTM_SECTION_IDS: readonly ["offer", "proof", "voice", "icp", "buyers", "problems", "objections", "signals", "learnings", "memories"];
+export type GtmSectionId = (typeof GTM_SECTION_IDS)[number];
+/** The reads a GTM context makes, each a workspace operation. */
+export declare const GTM_CONTEXT_READS: readonly ["getOutreachProfile", "listIcps", "getIcp", "listIcpProducts", "getIcpFitInsights", "listAgentMemories"];
+export type GtmContextReadId = (typeof GTM_CONTEXT_READS)[number];
+export type GtmReadInput = {
+    params?: Record<string, string>;
+};
+/** A reader's answer when an ICP read was refused because this person's role can't read ICPs, such as a member. */
+export declare const GTM_READ_DENIED: unique symbol;
+/**
+ * The reason an ICP route gives a 403 for that role: the route's `code`, and
+ * `error.details.reason` through the workspace API. Any other refusal is a
+ * failed read, so it never lets the agent draft without the ICP's rules.
+ */
+export declare const ICP_ROLE_REFUSAL = "icp_profile_manager_required";
+/** Runs one workspace read as the user: its data, GTM_READ_DENIED, or null when it failed or this connection can't make it. */
+export type GtmContextReader = (operationId: GtmContextReadId, input: GtmReadInput) => Promise<unknown>;
+/** Sections each task reads, most useful first. Fit insights are read only where a task lists them. */
+export declare const TASK_SECTIONS: Record<GtmContextTask, readonly GtmSectionId[]>;
+export declare const GTM_CONTEXT_CHARS: {
+    readonly min: 1500;
+    readonly default: 6000;
+    readonly max: 10000;
+};
+export declare const gtmContextInputSchema: z.ZodObject<{
+    task: z.ZodEnum<["messaging", "targeting", "objections", "call_prep", "overview"]>;
+    focus: z.ZodOptional<z.ZodString>;
+    icp_id: z.ZodOptional<z.ZodString>;
+    product_id: z.ZodOptional<z.ZodString>;
+    sections: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEnum<["offer", "proof", "voice", "icp", "buyers", "problems", "objections", "signals", "learnings", "memories"]>, "many">, ("signals" | "icp" | "problems" | "objections" | "offer" | "proof" | "voice" | "buyers" | "learnings" | "memories")[], ("signals" | "icp" | "problems" | "objections" | "offer" | "proof" | "voice" | "buyers" | "learnings" | "memories")[]>>;
+    max_chars: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    task: "messaging" | "objections" | "targeting" | "call_prep" | "overview";
+    max_chars: number;
+    icp_id?: string | undefined;
+    product_id?: string | undefined;
+    focus?: string | undefined;
+    sections?: ("signals" | "icp" | "problems" | "objections" | "offer" | "proof" | "voice" | "buyers" | "learnings" | "memories")[] | undefined;
+}, {
+    task: "messaging" | "objections" | "targeting" | "call_prep" | "overview";
+    icp_id?: string | undefined;
+    product_id?: string | undefined;
+    focus?: string | undefined;
+    sections?: ("signals" | "icp" | "problems" | "objections" | "offer" | "proof" | "voice" | "buyers" | "learnings" | "memories")[] | undefined;
+    max_chars?: number | undefined;
+}>;
+export type GtmContextInput = z.infer<typeof gtmContextInputSchema>;
+/** One tool definition for the agent and MCP. */
+export declare const GTM_CONTEXT_TOOL: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            task: {
+                type: string;
+                enum: ("messaging" | "objections" | "targeting" | "call_prep" | "overview")[];
+                description: string;
+            };
+            focus: {
+                type: string;
+                maxLength: number;
+                description: string;
+            };
+            icp_id: {
+                type: string;
+                format: string;
+                description: string;
+            };
+            product_id: {
+                type: string;
+                format: string;
+                description: string;
+            };
+            sections: {
+                type: string;
+                items: {
+                    type: string;
+                    enum: ("signals" | "icp" | "problems" | "objections" | "offer" | "proof" | "voice" | "buyers" | "learnings" | "memories")[];
+                };
+                minItems: number;
+                maxItems: 10;
+                uniqueItems: boolean;
+                description: string;
+            };
+            max_chars: {
+                type: string;
+                minimum: 1500;
+                maximum: 10000;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    inputError: string;
+};
+/** Offered to a connection that can make its core reads: the outreach profile or the ICPs. */
+export declare function offersGtmContext(scopes: readonly string[]): boolean;
+export type GtmItem = {
+    ref: string;
+    text: string;
+};
+export type GtmSection = {
+    id: GtmSectionId | "guardrails";
+    title: string;
+    /** Where the items come from, as the app names it. */
+    source: string;
+    items: GtmItem[];
+    /** Items left out to stay within the budget. */
+    omitted: number;
+};
+export type GtmLink = {
+    label: string;
+    href: string;
+};
+export type GtmGap = {
+    section: GtmSectionId;
+    reason: string;
+    fix: GtmLink;
+};
+export type GtmContext = {
+    task: GtmContextTask;
+    focus: string | null;
+    icp: {
+        id: string;
+        name: string;
+        version: number | null;
+        updated_at: string | null;
+    } | null;
+    /** Other published ICPs, to read one by its ID. */
+    other_icps: {
+        id: string;
+        name: string;
+    }[];
+    /** The connected Product read with an ICP that keeps its guidance on its Products. */
+    product: {
+        id: string;
+        name: string;
+    } | null;
+    /** The ICP's other connected Products, to read one by its ID. */
+    other_products: {
+        id: string;
+        name: string;
+    }[];
+    sections: GtmSection[];
+    /** True when the outreach profile's and this ICP's guardrails were all read. A campaign's own rules aren't part of it. */
+    guardrails_complete: boolean;
+    /** True when every guardrail source was read but several ICPs are published and none was named. */
+    guardrails_need_icp: boolean;
+    /** True when the ICP keeps its guidance on several connected Products and none was named. */
+    guardrails_need_product: boolean;
+    /**
+     * True when the only guardrails left unread are the ICP's, because this
+     * person's workspace role can't read ICPs. Everything else was read.
+     */
+    guardrails_role_limited: boolean;
+    missing: GtmGap[];
+    /** Reads that failed or were not allowed; what they hold is unknown, not empty. */
+    unavailable: string[];
+    /** Facts about the context itself, such as an unconfirmed profile. */
+    notes: string[];
+    /** max_chars and used_chars cover the items other than guardrails. */
+    budget: {
+        max_chars: number;
+        used_chars: number;
+        guardrail_chars: number;
+        omitted_items: number;
+    };
+    generated_at: string;
+};
+/** Screens that add what is missing. Every link is one the agent may show. */
+export declare const GTM_FIX_LINKS: {
+    readonly writing: "/dashboard/outreach/campaigns?settings=writing";
+    readonly icps: "/dashboard/account?section=saved-icps";
+    readonly pipeline: "/dashboard/pipeline";
+};
+/** What each read returned: undefined when not made, null when it failed or is not allowed. */
+export type GtmContextRaw = {
+    profile?: unknown;
+    icps?: unknown;
+    icp?: unknown;
+    products?: unknown;
+    insights?: unknown;
+    memories?: unknown;
+};
+/** The sections a call covers, in the task's order; asked-for sections the task doesn't list go last. */
+export declare function sectionsInScope(input: Pick<GtmContextInput, "task" | "sections">): GtmSectionId[];
+/** Builds a GTM context from its reads. Pure: the same reads always give the same context. */
+export declare function buildGtmContext(input: GtmContextInput, raw: GtmContextRaw, now: Date, options?: {
+    memoriesInPrompt?: boolean;
+}): GtmContext;
+/**
+ * Runs the reads: what is known up front (with a given icp_id, that ICP too),
+ * then the ICP the list points to.
+ */
+export declare function loadGtmContext(input: GtmContextInput, read: GtmContextReader, options?: {
+    now?: Date;
+    memoriesInPrompt?: boolean;
+}): Promise<GtmContext>;
+/** The context as Markdown, for chat, Slack and MCP. Links are relative to the app unless an origin is given. */
+export declare function gtmContextMarkdown(context: GtmContext, origin?: string): string;

package/types/shared/icp-product-selection.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export declare const icpProductSelectionRefSchema: z.ZodObject<{
+    id: z.ZodString;
+    icp_id: z.ZodString;
+    icp_version_id: z.ZodString;
+    product_id: z.ZodString;
+    product_version_id: z.ZodString;
+    link_id: z.ZodString;
+    link_version_id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    icp_id: string;
+    icp_version_id: string;
+    product_id: string;
+    product_version_id: string;
+    link_id: string;
+    link_version_id: string;
+}, {
+    id: string;
+    icp_id: string;
+    icp_version_id: string;
+    product_id: string;
+    product_version_id: string;
+    link_id: string;
+    link_version_id: string;
+}>;
+export type IcpProductSelectionRef = z.infer<typeof icpProductSelectionRefSchema>;