@honest-pitches/pitch-sdk

The JavaScript / TypeScript SDK for the Honest Pitches platform. Use it to define, list, update, and transition the pitches you own on honestpitches.com.

The SDK is a pure HTTP wrapper around the hosted MCP server at https://mcp.honestpitches.com. It has no backend vendor config: no endpoint, no projectId, no databaseId, no backend SDK dependency. One env var (PITCHER_API_KEY) is all you need.

This package is the source of truth for the pitcher-facing programmatic surface. The honest-pitches-cli and the honest-pitches-pitcher-mcp server are both thin wrappers around this SDK — they don't re-implement pitch logic.

Install

npm install @honest-pitches/pitch-sdk
# or
pnpm add @honest-pitches/pitch-sdk

The package is published publicly on npmjs.com. The source remains in the private Honest Pitches Forgejo repository.

Quickstart

The SDK authenticates with a per-user API key that you mint at studio.honestpitches.com → Settings → API keys. The key is long-lived; you pass it to the client factory once.

import { createPitcherClient } from "@honest-pitches/pitch-sdk";

// Get a key at studio.honestpitches.com → Settings → API keys,
// then set PITCHER_API_KEY in your environment:
const client = createPitcherClient({
  apiKey: process.env.PITCHER_API_KEY!,
});

const pitches = await client.pitches.find({ status: "live" });

PITCHER_MCP_URL defaults to the hosted MCP (https://mcp.honestpitches.com). Set it only when self-hosting the MCP.

The JWT variant is the same shape:

const client = createPitcherClient({
  jwt: process.env.PITCHER_JWT!, // short-lived per-user JWT (minted via the pitcher-mcp OAuth flow)
});

API

Client factory

| Export | Kind | Notes | | --- | --- | --- | | createPitcherClient(config) | factory | builds the client from { apiKey } or { jwt } | | resolvePitcherConfig(config) | helper | merges defaults with caller-supplied overrides | | DEFAULT_PITCHER_BASE_URL | constant | https://mcp.honestpitches.com — the hosted MCP |

Pitch operations

| Export | Kind | Notes | | --- | --- | --- | | PitchesApi | class | find / get / create / update / transition / uploadMedia / unarchive pitches | | scaffoldPitchFromFramework | helper | builds a section set from a framework key | | findCreatorIdForJwtUser | helper | looks up the creator $id from the auth principal | | findCreatorIdForApiKey | helper | same, for API-key auth |

Frameworks & segments

Re-exported from the SDK's framework module so you don't need a second import:

| Export | Kind | Notes | | --- | --- | --- | | loadFrameworks | function | returns every framework definition | | loadSegments | function | returns every segment definition | | getSegmentDefinition | function | single segment by key | | suggestedSectionsForFramework | function | default section list for a framework |

Error model

Every error thrown by this SDK is a PitcherSdkError (or one of its subclasses). The subclasses are:

• PitcherRequestError — the MCP server returned a non-2xx
• FrameworkLockedError — tried to change a pitch's framework after the first section was written
• HpCodeImmutableError — tried to change a pitch's hpCode after creation
• InvalidSectionKindError — section kind not in the framework's allowed set
• PitcherNotAuthenticatedError — token missing or expired
• PitcherNotOwnedCreatorError — token is valid but doesn't own this creator row

All errors expose a .code (a stable string identifier you can switch on without instanceof) and a .status (the HTTP status returned by the MCP server, where applicable).

TypeScript support

The package ships its own .d.mts declaration file. No additional @types/* packages are needed. The runtime bundle is fully self-contained: zero @honest-pitches/* runtime dependencies, zero backend SDK runtime dependency.

Build (for SDK maintainers)

pnpm install
pnpm build       # node build.mjs → dist/
pnpm test        # vitest run
pnpm typecheck   # tsc --noEmit

License

UNLICENSED — internal Honest Pitches use only. The package is published publicly on npmjs.com for the convenience of external developers building on top of the platform; redistribution and modification are not permitted.