@leadpoet/client 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadpoet/client",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Leadpoet API client, CLI, and MCP adapter",
   "license": "MIT",
@@ -8,6 +8,17 @@
     "node": ">=22"
   },
   "homepage": "https://leadpoet.com/docs/api",
+  "keywords": [
+    "leadpoet",
+    "sales",
+    "prospecting",
+    "lead-generation",
+    "b2b",
+    "crm",
+    "outreach",
+    "cli",
+    "mcp"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -29,7 +40,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.31.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "zod": "^3.25.76"
   }
 }

package/skill/SKILL.md

@@ -12,22 +12,80 @@ Credentials come from `LEADPOET_API_KEY`; `LEADPOET_API_BASE` selects the worksp
 deployment. Never print, paste into arguments, or commit keys. Switching
 workspaces means using a different explicitly selected credential.
 
+## Setup
+
+1. Sign up at https://leadpoet.com and
+   [request API access](https://leadpoet.com/docs/api#access) for the workspace.
+2. Install the CLI with `npm install -g @leadpoet/client`, or connect the MCP
+   server `https://leadpoet.com/mcp`, which signs in with OAuth and needs no key.
+3. For the CLI, create a key in Leadpoet under **Settings → Developer → API
+   keys** and set it as `LEADPOET_API_KEY`.
+
 ## Workflow
 
+Before planning an ICP, a request or a campaign, or drafting outreach, read
+`getPlaybook` (pass `topic` for one section: `target-market` for ICPs,
+`buying-signals`, `requests`, `accounts`, `messaging`, `campaigns`, `replies`, `plays` or
+`experiments` for results) and use it as guidance unless the user chooses
+otherwise. Each practice cites its studies; cite them when you advise. It never
+authorizes a spend, an archive or a stage change.
+
+Before drafting anything a prospect will read, planning targeting, or preparing
+for a call or an objection, read the workspace's own context. Over MCP, call
+`getGtmContext` with the matching `task` (`messaging`, `targeting`,
+`objections`, `call_prep` or `overview`) and the ICP's `icp_id`. It holds the
+workspace's context; for a campaign, also read the campaign: when its
+`advanced_settings` has a `campaign_product` that isn't null, or a
+`request_offer` with a `request_offer_policy`, write from that product, not
+from this context's offer, proof, lines or outcomes, and follow the campaign's
+own guidance too.
+With the CLI, read `getOutreachProfile` and `getIcp` yourself, and
+`listIcpProducts` when the ICP's `storage_schema_version` is 2: its connected
+Products hold its problems, objections and writing rules. State the user's
+offer, results and buyers only as that context states them, use only proof that
+is approved and current, and follow every guardrail (claims, topics, angles and
+phrases never to use, companies never to target). When `guardrails_need_icp`
+is true, call it again with the `icp_id` of the ICP you're writing for; when
+`guardrails_need_product` is true, with the `product_id` of the Product (for a
+campaign, the `product_id` in its `campaign_product.input.productSelection`); or ask the user which one. Until `guardrails_complete` is true, write nothing a
+prospect will read, unless `guardrails_role_limited` is true: then say the
+draft wasn't checked against the ICP's rules. When a section
+is missing, tell the user and link the screen it names; never invent it.
+Each saved objection comes with the seller's saved answer, or says none is
+saved (`objection_answers` in the ICP or Product guidance). To answer an
+objection, use its saved answer and add no claim, number, comparison, customer
+or benefit it doesn't state. When none is saved, write no rebuttal of your own:
+tell the user and offer to save one where that objection is saved, on the ICP
+or its Product.
+
 1. Read `getCredits`, `getContactAllowance`, the `createRequest` contract and the
    user's targeting requirements. Establish quantity and credit budget within the
-   user's authorization. `getPricing` describes the separate legacy sourcing lane;
-   it is unavailable during the workspace-only pilot and must not set its budget.
-   Persist a fresh retry key with the request body. Call `createRequest`; save
-   its `query_id`, `icp_id` and reservation information.
-2. Use `leadpoet wait <query_id> --timeout 300` or bounded `getRequest` polling.
-   A queued or timed-out operation is pending, not failed or completed. Inspect
-   the saved request before submitting again. Read `getPipeline` and
+   user's authorization. Always send `contacts_per_company` and
+   `included_contacts_per_company`; `credit_budget` must then equal the exact total:
+   `max_leads × (credits_per_company + credits_per_extra_contact × contacts above
+   included_contacts_per_company + credits_per_mobile_contact × contacts_per_company
+   when mobile is requested)`, using `getContactAllowance.pricing`. The minimum is
+   100 credits (ten companies with one included contact); 10 companies with 2
+   contacts and 1 included cost 150. A request must leave at least 100 credits,
+   or less than the request's price per company. Tell the user the total
+   before submitting.
+   Persist a fresh UUID retry key with the request body.
+   Call `createRequest`; save its `query_id`, `icp_id` and reservation information.
+2. Requests are researched and verified by Leadpoet, with a typical turnaround
+   of 1–2 days. Tell the user the request is running,
+   then check `getRequest` later; `progress.state` is `working`, `ready`,
+   `failed` or `archived` (won't be fulfilled), and `progress.check_again_after_seconds` suggests when to look again.
+   Do not poll in a tight loop or resubmit. Pending work is not failed or
+   completed. Inspect the saved request before submitting again. Read `getPipeline` and
    `listPipelineContacts` with its ICP ID. Preserve evidence and qualification;
    do not fill missing fields or describe inferred leads as verified.
 3. For outreach, discover accounts, audience contacts and sequence templates.
    Preview and save an audience, create a campaign draft, and read its preview
    and contract proposal. Use the returned IDs and exact current revisions.
+   Drop an unwanted draft with `discardCampaign`; `archiveCampaign` applies only
+   to paused or completed campaigns. When an ICP draft reports
+   `storage_schema_version: 2`, update it with `schema_version: 2`,
+   `company_fit` and `buyer_groups` only.
 4. Launch, resume, approve messages, or reply only when the user has authorized
    that send action, recipients and content. A broad request to research or
    prepare outreach does not authorize sending. CLI sends require `--allow-send`;
@@ -39,6 +97,15 @@ workspaces means using a different explicitly selected credential.
    response does not prove delivery. Report saved state, pending work, failures,
    cost information and the next useful action without exposing contact data
    beyond the user's requested result.
+6. Leadpoet learns what works for the workspace from fit ratings, deal outcomes
+   and campaign reviews. Before changing an ICP or planning a request, read
+   `getIcpFitInsights` for that ICP; before changing a campaign, read
+   `getCampaignReviews`. Show what they found with its counts, as evidence for
+   the user to weigh. When the user says a company or contact is or is not a
+   good fit, record it with `rateCompanyFit` and the reason they gave; never
+   rate on your own judgment. When the user reports a meeting, a win or a loss,
+   offer to move the contact or deal to match, with the outcome reasons a
+   closed deal needs.
 
 ## Calls and recovery
 
@@ -47,10 +114,11 @@ and returns a JSON envelope with `data` and `request_id`.
 
 ```sh
 leadpoet call getPipeline --query '{"icp_id":"<saved-icp-uuid>"}'
-leadpoet call createCampaign --input campaign.json --idempotency-key campaign-0001
+leadpoet call createCampaign --input campaign.json --idempotency-key "$CAMPAIGN_KEY"
 ```
 
-Keep the same retry key, actor and identical body after interruption. Never
+Use a fresh UUID for each logical write. Keep the same retry key, actor and
+identical body after interruption. Never
 replace a send key to force success. The client does not automatically retry
 writes. For `none`, inspect saved state before deciding whether another call is
 safe. For revision or approval conflicts, reread and review; never silently
@@ -62,3 +130,9 @@ Pagination differs by operation. Follow its declared page/cursor contract;
 bounded snapshots and `results_limited` are not complete exports. Do not infer
 that a missing item does not exist. Never bypass consent, ownership, suppression,
 credit, evidence or feature gates. Account consent remains in the application.
+
+## Report a problem
+
+If a call keeps failing with a `5xx` or returns a result that looks wrong, tell
+the user they can report it to hello@leadpoet.com with the operation name, the
+time and the `request_id`. Leave out keys, contact data and message text.

package/types/scripts/leadpoet-mcp.d.ts

@@ -1,7 +1 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { LeadpoetClient } from "../shared/leadpoet-client";
-/** The API's own "still working" message for an unfinished request, so agents relay it instead of polling. */
-export declare function progressNotice(data: unknown): string | null;
-export declare function createLeadpoetMcpServer(client: LeadpoetClient, options?: {
-    allowSend?: boolean;
-}): Promise<Server>;
+export { createLeadpoetMcpServer, progressNotice, type LeadpoetMcpServerOptions } from "../shared/leadpoet-mcp-server";