@leadpoet/client 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# Leadpoet API clients
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared TypeScript client, CLI, MCP server and skill use `/api/v1`. Each call
+uses the same API-key permissions and saved workflow as the application. The
+package is published to npm as `@leadpoet/client`.
+
+## Request access and install
+
+[Request access](https://leadpoet.com/contact) with your intended workflow and
+whether you need the CLI, TypeScript client, MCP or skill. Leadpoet will enable
+API access for your workspace. Once enabled,
+manage your keys in Account → Developer → API keys.
+
+Agents can start at [the API guide](https://leadpoet.com/docs/api#agents).
+Request https://leadpoet.com/docs/api with `Accept: text/markdown` for a concise
+machine-readable guide, then use the linked OpenAPI schema for current inputs.
+
+With Node.js 22 or later, install the package:
+
+```sh
+npm install -g @leadpoet/client
+```
+
+For the TypeScript client, run `npm install @leadpoet/client` in your project.
+
+Set `LEADPOET_API_KEY` through your shell's secret manager and
+`LEADPOET_API_BASE=https://leadpoet.com/api/v1` for the enabled deployment.
+The credential selects the workspace. Use a separate client instance or process
+environment for another workspace. Never put a key in arguments, a checked-in
+config, browser code, or logs. Only HTTPS and localhost HTTP bases are accepted;
+redirects are rejected. Installing a client does not grant API access or change
+your key permissions.
+
+## CLI
+
+```sh
+leadpoet operations
+leadpoet call getCredits
+leadpoet call getContactAllowance
+leadpoet describe createRequest
+leadpoet call createRequest --input request.json --idempotency-key request-0001
+leadpoet wait '<returned-query-uuid>' --timeout 300
+leadpoet call getPipeline --query '{"icp_id":"<returned-icp-uuid>"}'
+leadpoet describe createCampaign
+leadpoet call createCampaign --input campaign.json --idempotency-key campaign-0001
+```
+
+`--input -` reads a bounded JSON body from stdin. `--params` sets UUID path
+parameters and `--query` sets documented query fields. Output is always JSON,
+except help. Options apply only to their documented command; unsupported options
+are rejected before any request. Errors go to stderr and retain safe error codes, correlation IDs
+and Retry-After values, including when a proxy returns a non-JSON error body.
+Non-JSON response bodies are not exposed. Exit codes are 0 success, 1 transport/server failure,
+2 invalid input, 3 credentials/permissions, 4 conflict, 5 throttled, and
+6 pending timeout or terminal request failure, and 130 interrupted. Ctrl-C cancels
+discovery, polling, response reads and stdin input; an
+interrupted write may already have committed. Requests finish as `ready` or
+`error`; a successful HTTP response does not imply a successful sourcing result.
+The current workspace flow may stay `pending` until Leadpoet starts fulfillment.
+A polling timeout does not cancel the saved request.
+
+Send-authorizing operations require `--allow-send` and all advertised API scopes.
+This includes active-campaign changes and recurring request activation, not
+just immediate sends. `createRequest` with `body.recurrence` also requires
+`outreach:send` and explicit consent (`--allow-send` in the CLI or `allowSend: true`
+in the SDK). MCP additionally requires host send enablement; ordinary one-time
+requests remain available without it. Inspect `describe` before acting; it returns the operation plus referenced
+OpenAPI components. No write is retried
+automatically. Preserve the original key, actor and body after uncertainty.
+
+## TypeScript client
+
+```ts
+import { LeadpoetClient } from '@leadpoet/client';
+
+const client = new LeadpoetClient({
+  baseUrl: process.env.LEADPOET_API_BASE!,
+  apiKey: process.env.LEADPOET_API_KEY!,
+});
+const result = await client.call('getPipeline', { query: { icp_id: savedIcpId } });
+const settled = await client.waitForRequest(savedQueryId, { timeoutMs: 300_000 });
+for await (const page of client.requestPages({ limit: 25, maxPages: 20 })) {
+  // Read page.data.queries; preserve IDs and provenance.
+}
+```
+
+Operation names and the transport envelope are typed. Workflow payloads retain
+their native JSON extensions; `describe`/OpenAPI carries the registered input
+schemas and stable response fields. A caller can supply a validated result type
+to `call<T>`. This is not a generated SDK that statically types every workflow
+field. The OpenAPI `x-pagination` extension distinguishes cursor/page lists from
+bounded snapshots. The `x-query-schema` extension preserves conditional query
+requirements (for example, account pipeline configuration requires `icp_id`) for
+MCP validation. Audience contact filters are a JSON-encoded query string.
+Malformed history/status responses, including unknown request statuses, fail with
+`invalid_response` and retain the request ID. Timeouts and polling intervals use bounded integer milliseconds.
+Only request history has a built-in page iterator; other
+cursors must be advanced according to that operation's contract. Preserve
+partial/degraded/limited markers instead of calling a snapshot a complete export.
+
+## MCP
+
+Use a local stdio server with an MCP host. `npx` fetches the package, so no
+separate install is needed:
+
+```json
+{
+  "mcpServers": {
+    "leadpoet": {
+      "command": "npx",
+      "args": ["-y", "-p", "@leadpoet/client", "leadpoet-mcp"],
+      "env": {
+        "LEADPOET_API_BASE": "https://leadpoet.com/api/v1",
+        "LEADPOET_API_KEY": "<supply-through-your-host-secret-store>"
+      }
+    }
+  }
+}
+```
+
+The adapter uses the [official MCP TypeScript SDK](https://ts.sdk.modelcontextprotocol.io/server).
+It discovers the deployment's OpenAPI schemas, exposes only the compiled
+operation allowlist, validates tool arguments, and calls the shared client.
+It uses no listening HTTP port, OAuth impersonation, provider credentials or
+database access. Stdout is reserved for MCP protocol messages.
+
+Send tools are omitted by default. To expose them deliberately, set
+`LEADPOET_MCP_ALLOW_SEND=1`; each send tool also requires `allowSend: true` and
+the server-enforced scopes. Client enablement never widens the key's permissions.
+Errors remain tool errors with actionable status/correlation information.
+
+The package includes `skill/SKILL.md`; its source is
+`agent-skills/leadpoet-workspace/SKILL.md`. Install that directory using your
+agent's normal skill installation workflow. It teaches sourcing, saved pipeline
+results, campaign preparation, explicit send authorization and uncertain-outcome
+recovery. Skill installation does not grant API access or authorize sending.
+
+## Verification and boundaries
+
+Focused tests execute actual CLI processes and MCP stdio against an isolated
+API HTTP fixture for two workspaces. Native controller tests separately verify
+permissions, paid-request creation/replay and held campaign creation/replay.
+The migration test runs exact SQL in disposable embedded PostgreSQL. These are
+local checks, not evidence that a production deployment has been enabled.
+
+Account consent/OAuth, provider migration/connection administration, multipart
+uploads, network prospecting and CRM administration remain in their existing
+application workflows. This package covers the published operation catalog;
+it does not expose arbitrary private application routes.
+
+## Build from source
+
+For repository contributors with the locked dependencies installed:
+
+```sh
+npm run build:api-clients
+npm pack ./dist/leadpoet
+```
+
+Releases are published to npm as `@leadpoet/client` from the built
+`dist/leadpoet` directory.