@honest-pitches/pitch-sdk 0.4.6 → 0.5.1

package/CHANGELOG.md

@@ -179,6 +179,86 @@ across 6 contract files). See
 `CHANGELOG.d/2026-07-20-publish-fix-and-readme.md` for the long-form
 publish-failure root-cause analysis and the full README diff.
 
+## [0.5.1] - 2026-07-25
+
+First publish that matches the documented design end-to-end. Three
+coordinated changes:
+
+### Vendor-agnostic HTTP wrapper (the v0.5.0 re-architecture, finally published)
+
+The SDK is now a pure HTTP wrapper against the pitcher-mcp server's
+`/pitcher/*` routes. Consumers only need `{ apiKey: 'hp_pk_…' }` —
+no `endpoint`, no `projectId`, no backend env vars, no vendor
+imports in the public API surface. The package no longer depends
+on `node-appwrite` (audit 3 confirmed: the bundle is `node-appwrite`-free).
+The MCP server is the only layer that knows about the backend;
+the SDK and the consumer are both HTTP-only.
+
+### ESM bundle fix (the actual blocker)
+
+The v0.5.0 build produced an ESM bundle that threw `Dynamic require
+of "path" is not supported` at module-load time on Node 20+,
+100% of consumers. Root cause: esbuild's CJS-shim `__require(x)`
+in the ESM bundle fails for Node built-ins because pure ESM has no
+`require`. The fix is a `banner: { js: "import { createRequire as
+topLevelCreateRequire } from 'node:module'; const require =
+topLevelCreateRequire(import.meta.url);" }` on the ESM esbuild
+call in `build.mjs`. Same pattern as the Node-ESM target in
+`honest-pitches-platform-libs/packages/pitch-core/tsup.config.ts`.
+
+**Why v0.4.6 also failed** (transitive from
+`pitcher-api-key-core`'s `require("crypto")`): the same root cause,
+different inlined vendor. The 0.4.6 → 0.5.x lineage fixes it
+identically.
+
+### Publish workflow hardening
+
+The publish workflow now runs `pnpm test:ci` (not `pnpm test`)
+so the contract tests are no longer silently skipped. The new
+`scripts/esm-bundle-runtime.contract.test.mjs` (2 cases) is the
+regression pin — it would have caught v0.4.6 at publish time.
+`scripts/publish-workflow.contract.test.mjs` (now 15 cases) adds
+a `Test step runs pnpm test:ci` assertion.
+
+### What ships
+
+- `dist/index.cjs` — CJS bundle (works as before)
+- `dist/index.mjs` — ESM bundle (FIXED; loads cleanly on Node 20+)
+- `dist/index.d.mts` — TypeScript declarations
+- `package.json` (`0.5.1`) — version bump from `0.5.0`
+- `src/config.ts` — drops `endpoint`/`projectId`/`databaseId`/`client`/`initialJwt`, adds `apiKey`/`jwt`/`jwtExpiresAt`/`baseUrl`/`fetchImpl`
+- `src/pitches.ts` + `src/creators.ts` — uses `fetchPitches` against `${baseUrl}/pitcher/*`
+- `src/errors.ts` — adds `PitcherRequestError` (replaces `AppwriteRequestError`)
+- `dist/*` typings — drop `MEDIA_API_FUNCTION_ID` / `PUBLIC_API_FUNCTION_ID` / `STRIPE_API_FUNCTION_ID` / `STUDIO_API_FUNCTION_ID` / `appwriteQueryEqual` / `appwriteQueryLimit`
+
+### What does NOT ship in this version
+
+- The CLI (`@honest-pitches/hp-cli`) lives at `D:\Honest_Pitches\honest-pitches-cli` and is already a separate package.
+- The `drp-*` framework IDs in the public `/agents/` page are wrong (should be `drtv_*` from the local frameworks registry). Tracked as a follow-up ticket against the public web repo, not the SDK.
+- The MCP server's `/pitcher/*` route table is the live source of truth; the SDK's `fetchPitches` client mirrors it.
+
+### Test surface
+
+- `pnpm test` (Vitest) — 53 unit tests pass.
+- `pnpm test:ci` (Vitest + 9 contract tests) — 53 + 49 = 102 cases pass.
+- `scripts/esm-bundle-runtime.contract.test.mjs` (NEW, 2 cases) — RED on 0.5.0, GREEN on 0.5.1.
+- `scripts/publish-workflow.contract.test.mjs` (15 cases, +1) — asserts `pnpm test:ci` runs in the workflow.
+- `scripts/no-node-appwrite-in-runtime.contract.test.mjs` (4 cases) — `node-appwrite` is absent from the bundle.
+- `scripts/bundled-deps.contract.test.mjs` (10 cases) — the bundle is fat and self-contained.
+- `scripts/config-shape.contract.test.mjs` (3 cases) — `endpoint`/`projectId` are absent from the public API.
+
+### Acceptance (brief)
+
+- [x] `createPitcherClient({ apiKey: 'hp_pk_…' })` builds with no other config.
+- [x] The build's only network surface is `${PITCHER_MCP_URL}/pitcher/*`, defaulting to `https://mcp.honestpitches.com`.
+- [x] `import '@honest-pitches/pitch-sdk'` works on Node 20+ (no `Dynamic require of "path"`).
+- [x] `require('@honest-pitches/pitch-sdk')` works (unchanged).
+- [x] `0.4.6` is recommended for deprecation (`pnpm deprecate` is a publish pipeline action — separate follow-up).
+
+See `CHANGELOG.d/2026-07-25-vendor-agnostic-esm-fix.md` for the
+long-form root-cause analysis and audit 3 (SDK contract drift)
+findings.
+
 ## [0.3.0] - 2026-06-17
 
 See `CHANGELOG.d/2026-06-17.md` for the change set.

package/README.md

@@ -2,17 +2,17 @@
 
 The JavaScript / TypeScript SDK for the **Honest Pitches** platform.
 Use it to define, list, update, and transition the pitches you own on
-[honestpitches.com](https://www.honestpitches.com) — the place where
-founders publish their real numbers, real plans, and real backers, and
-critics respond with structured ratings instead of hot takes.
+[honestpitches.com](https://www.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. A developer who uses
-the CLI gets exactly the same SDK calls a developer who uses the MCP
-server gets: same auth, same errors, same pagination, same audit
-trail.
+this SDK — they don't re-implement pitch logic.
 
 ## Install
 
@@ -27,22 +27,32 @@ The source remains in the private Honest Pitches Forgejo repository.
 
 ## Quickstart
 
-The SDK authenticates with a **per-user token** that you obtain from
-the platform's OAuth flow. The token is short-lived; you mint it once
-per session and pass it to the client factory. The SDK will refresh
-internally on 401 responses.
+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.
 
 ```ts
 import { createPitcherClient } from "@honest-pitches/pitch-sdk";
 
-// Mint a per-user JWT via your platform OAuth flow, then:
+// Get a key at studio.honestpitches.com → Settings → API keys,
+// then set PITCHER_API_KEY in your environment:
 const client = createPitcherClient({
-  endpoint: process.env.HONEST_PITCHES_ENDPOINT!,  // the platform base URL
-  projectId: process.env.HONEST_PITCHES_PROJECT_ID!,
-  initialJwt: process.env.PITCHER_JWT!,  // short-lived per-user JWT
+  apiKey: process.env.PITCHER_API_KEY!,
 });
 
-const pitches = await client.pitches.list({ status: "live" });
+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:
+
+```ts
+const client = createPitcherClient({
+  jwt: process.env.PITCHER_JWT!, // short-lived per-user JWT (minted via the pitcher-mcp OAuth flow)
+});
 ```
 
 ## API
@@ -51,17 +61,18 @@ const pitches = await client.pitches.list({ status: "live" });
 
 | Export | Kind | Notes |
 | --- | --- | --- |
-| `createPitcherClient(config)` | factory | builds the client; `initialJwt` is a short-lived per-user JWT, NOT a long-lived API key |
+| `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 | list / get / create / update / transition pitches |
+| `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 a JWT's `sub` claim |
-| `findCreatorIdForApiKey` | helper | server-side variant for API-key auth |
+| `findCreatorIdForJwtUser` | helper | looks up the creator `$id` from the auth principal |
+| `findCreatorIdForApiKey` | helper | same, for API-key auth |
 
 ### Frameworks & segments
 
@@ -75,70 +86,28 @@ second import:
 | `getSegmentDefinition` | function | single segment by key |
 | `suggestedSectionsForFramework` | function | default section list for a framework |
 
-### Query helpers
-
-The SDK uses a small query DSL internally and exposes the building
-blocks so you don't have to re-import them:
-
-| Export | Kind | Notes |
-| --- | --- | --- |
-| `appwriteQueryEqual` | helper | `field == value` |
-| `appwriteQueryLimit` | helper | pagination cap |
-
-> The `appwrite*` prefix on these helpers is a naming artifact from
-> the SDK's internal implementation; you don't need to know what
-> backs them to use them. The names are stable — they're part of
-> the published API.
-
-### Token parsing
-
-| Export | Kind | Notes |
-| --- | --- | --- |
-| `decodeJwtSub` | helper | extracts the `sub` claim without verifying the signature |
-| `isJwtExpired` | helper | `true` if the token's `exp` is in the past |
-
-### Routing constants
-
-| Export | Kind | Notes |
-| --- | --- | --- |
-| `MEDIA_API_FUNCTION_ID` | constant | the platform's media-handling function id |
-| `PUBLIC_API_FUNCTION_ID` | constant | the public read API function id |
-| `STRIPE_API_FUNCTION_ID` | constant | the Stripe integration function id |
-| `STUDIO_API_FUNCTION_ID` | constant | the studio integration function id |
-| `resolveConsolidatedRoute` | function | picks the right function id for a given request |
-
 ## Error model
 
 Every error thrown by this SDK is a `PitcherSdkError` (or one of its
 subclasses). The subclasses are:
 
-- `AppwriteRequestError` — the backend returned a non-2xx (the
-  prefix is a naming artifact from the SDK's internal implementation;
-  the error fires for any backend non-2xx, not just the Appwrite
-  transport)
+- `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 `.cause` (the original underlying exception where
-applicable) and a `.code` (a stable string identifier you can switch
-on without `instanceof`).
+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.
-
-> **Note for TypeScript consumers.** The declaration file
-> `dist/index.d.mts` re-exports a small number of framework and
-> segment type aliases. These types are inlined (via `export type`)
-> so consumer-side `tsc` works without any extra `paths` mapping in
-> your `tsconfig.json`. If you see a `TS2307` "cannot find module
-> `@honest-pitches/pitch-core`" error, you have an older copy of the
-> SDK — upgrade to `>=0.4.6`.
+self-contained: zero `@honest-pitches/*` runtime dependencies,
+zero backend SDK runtime dependency.
 
 ## Build (for SDK maintainers)
 
@@ -154,4 +123,4 @@ pnpm typecheck   # tsc --noEmit
 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.
+modification are not permitted.