@honest-pitches/pitch-sdk 0.4.6 → 0.5.2

package/CHANGELOG.md

@@ -11,6 +11,72 @@ and this project adheres to
 
 ## [Unreleased]
 
+### Fixed
+
+- **`client.pitches.list is not a function` on every auth-required
+  list path (2026-07-28).** The `list` alias existed in local
+  source under the 0.5.1 version number but was never published
+  to npmjs (the 0.5.1 tarball only had `find`). Bumped to
+  **0.5.2** so a fresh `npm install @honest-pitches/pitch-sdk`
+  actually gets the alias. TSDoc updated to say stable-since
+  0.5.2 (honest about the 0.5.1 publish gap). Detail:
+  control-repo
+  [`CHANGELOG.d/2026-07-28-sdk-list-alias-and-creatorid-filter.md`](../CHANGELOG.d/2026-07-28-sdk-list-alias-and-creatorid-filter.md).
+
+### Fixes
+
+- **`videoSource` type widening to keep `pnpm run build:deploy:all`
+  green (commit `86f7ab1`, 2026-07-27).** The 2026-07-27 bug #2
+  commit `7f8b748` (`feat(pitcher-sdk): forward
+  videoSource/videoExternalId/videoExternalUrl + video helpers on
+  create/update`) widened `CreatePitchInput.videoSource` to a
+  3-literal union (`"bunny_video_id" | "external_url" | "none" |
+  null`) AND added an `input.videoSource !== ""` guard at
+  `src/pitches.ts:215`. The guard's intent — drop empty-string
+  form-field values from the wire body — is correct, but the
+  type doesn't permit `""`, so tsc flagged the comparison as
+  unreachable (TS2367) and `pnpm run build:deploy:all` failed at
+  the SDK build step. **Fix:** widen the union to add `""` on
+  both `CreatePitchInput` and `UpdatePitchInput` (the latter for
+  symmetry, since the spread-forward site could see an
+  empty-string value too). `""` now lives in the canonical
+  "do not overwrite" club alongside `null` and absent, matching
+  the MCP server's `raw[key] !== ""` guard at `pitch-write`.
+  Two pre-existing typecheck failures from the same
+  `7f8b748` commit were also repaired:
+  - **9× TS2741** — pitch-test sections were missing the
+    required `mediaIds: string[]` field (the `PitchSection`
+    contract has required it since at least the v0.3.0
+    platform-libs cut). Added `mediaIds: []` to all three
+    test-section triples.
+  - **1× TS7006** — `Headers.forEach((v, k) => …)` had
+    implicit-any parameters because the outer
+    `vi.fn(async (input: any, init?: any) => …)` signature
+    leaves `init` untyped, so the `instanceof Headers`
+    narrowing does not propagate to `init.headers`. Added
+    explicit `(v: string, k: string)` types.
+
+### Tests
+
+- **New regression test** (2026-07-27):
+  `pitches.test.ts#PitchesApi.create — body builder
+  does NOT forward videoSource/videoExternalId/videoExternalUrl
+  when set to empty string (regression: form-field hygiene)`.
+  Pins the `!== ""` guard's runtime behaviour — without it, a
+  future refactor that drops the guard would silently start
+  writing `""` to the server, which the server then rejects or
+  misinterprets depending on column nullability.
+- **Test counts:** `pnpm test` 47/47 vitest (was 46/46);
+  `pnpm test:ci` 47 vitest + 54 contract assertions across 9
+  contract suites, 0 regressions.
+
+### Version
+
+- **No version bump in this commit.** The bug #2 commit
+  (`7f8b748`) was unversioned at HEAD; this fix lands on top.
+  The next operator-pushed SDK tag should cut `v0.5.2` to ship
+  both fixes together.
+
 Next package version: `0.4.1`. See
 `CHANGELOG.d/2026-07-19-package-rename.md` for the rename to
 `@honest-pitches/pitch-sdk`.
@@ -179,6 +245,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.