@honest-pitches/pitch-sdk 0.4.6

package/CHANGELOG.md

@@ -0,0 +1,197 @@
+# Changelog
+
+All notable changes to `@honest-pitches/pitch-sdk` will be
+documented in this file. Per-date detail lives in
+`CHANGELOG.d/YYYY-MM-DD.md`.
+
+The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Next package version: `0.4.1`. See
+`CHANGELOG.d/2026-07-19-package-rename.md` for the rename to
+`@honest-pitches/pitch-sdk`.
+
+See `CHANGELOG.d/2026-06-23.md`, `CHANGELOG.d/2026-06-25-link-protocol.md`,
+and `CHANGELOG.d/2026-07-18-publish-to-public-npmjs.md` for the earlier
+change sets.
+
+## [0.4.3] - 2026-07-19
+
+The CI build that v0.4.2 was supposed to ship finally ships:
+`pnpm install --frozen-lockfile` succeeds (lockfile is now committed),
+the build reads from the vendored `vendor/platform-libs/<pkg>/dist/`
+snapshot instead of the sibling workspace, and no `prebuild` step is
+needed. All `pnpm test:ci` tests green (56 Vitest + 36 contract tests).
+See `CHANGELOG.d/2026-07-19-vendor-snapshot-ci-buildable.md` for the
+full change set and the v0.4.2 → v0.4.3 migration notes.
+
+## [0.4.4] - 2026-07-20
+
+Fixes the v0.4.3 CI build failure: `node build.mjs` failed with
+`Could not resolve "marked" / "sanitize-html" / "json5"` because the
+SDK's esbuild alias pointed at `pitch-core/dist/index.js` (the tsup
+**browser** target, which leaves `marked`/`sanitize-html`/`json5` as
+external imports for Vite to bundle at the Studio SPA build time).
+The SDK runs under Node — no Vite — so the unresolved imports broke
+the build. The fix aliases to `pitch-core/dist/index.cjs` (the tsup
+**CJS** target, which has those three deps **inlined** via tsup's
+`noExternal: ["marked", "sanitize-html", "json5"]`). The published
+SDK tarball stays self-contained — zero runtime deps for external
+consumers to install. See
+`CHANGELOG.d/2026-07-20-pitch-core-cjs-alias.md` for the long-form
+explanation and the browser-vs-node-vs-cjs tsup-target distinction.
+
+## [0.4.5] - 2026-07-20
+
+Fixes the v0.4.4 CI test failure that the v0.4.4 commit missed. The
+v0.4.4 fix changed `build.mjs` to alias `pitch-core` to its `index.cjs`
+target — but did **not** update `vitest.config.ts` to match. The CI
+build now succeeded, but `vitest run` in CI failed with
+`Error: Cannot find package 'marked' imported from '.../vendor/platform-libs/pitch-core/dist/index.js'`
+because vitest was still aliasing to the browser target.
+
+Worse — once vitest's alias was also pointed at `index.cjs`, the test
+runner hit a deeper issue: `pitch-core/dist/index.cjs` does a bare
+`require("@honest-pitches/hp-codes")` at line 15448, and **vitest
+does not apply `resolve.alias` to `require()` calls inside already-loaded
+CJS bundles** (per the official vitest docs: "Vitest does not support
+aliasing require calls."). Vitest's loader hits Node's native resolver,
+which can't find `@honest-pitches/hp-codes` in the SDK's `node_modules/`
+(the SDK deliberately has zero `@honest-pitches/*` runtime deps — that
+is the "fat SDK" contract).
+
+The fix is at the **vendoring layer**, not the vitest config:
+`scripts/copy-vendor-dist.mjs` now has a `rewriteInternalBareSpecifiers`
+pass that rewrites the vendored pitch-core bundles to use **relative
+paths** for cross-package `@honest-pitches/*` references
+(`require("../../hp-codes/dist/index.cjs")` instead of
+`require("@honest-pitches/hp-codes")`). After the rewrite, the vendored
+CJS bundle is self-contained for the SDK environment — the sibling
+file is physically present in `vendor/`, so the relative `require()`
+resolves without needing the alias map. Regression pin:
+`scripts/copy-vendor-dist.contract.test.mjs` ("vendored pitch-core
+bundles reference @honest-pitches/hp-codes by relative path, NOT bare
+specifier") and `scripts/bundled-deps.contract.test.mjs`
+("vitest.config.ts aliases @honest-pitches/pitch-core to
+vendor/.../index.cjs (MUST match build.mjs)").
+
+All `pnpm test:ci` tests green (56 Vitest + 38 contract tests across
+5 contract files). `pnpm build` produces the same self-contained
+fat-SDK tarball. See
+`CHANGELOG.d/2026-07-20-vendored-internal-relative-paths.md` for the
+full root-cause analysis and the vitest-vs-esbuild resolution story.
+
+## [0.4.6] - 2026-07-20
+
+Fixes the v0.4.5 publish failure and rewrites the README to be
+external-developer-facing (the v0.4.5 README leaked the Appwrite /
+TablesDB internal architecture, which is irrelevant to consumers).
+
+### Publish fix
+
+The v0.4.5 publish failed in CI with:
+
+```
+npm error code ENEEDAUTH
+npm error need auth This command requires you to be logged in to
+  https://git.neutronix.com/api/packages/honest-pitches/npm/
+```
+
+even though the workflow ran `pnpm config set @honest-pitches:registry
+https://registry.npmjs.org/` before publishing. Root cause: the
+project `.npmrc` declared `@honest-pitches:registry=https://git.neutronix.com/...`
+to route installs through the local Verdaccio mirror. That
+project-level config **OVERRIDES** the in-memory `pnpm config set`
+(per pnpm's config precedence: project `.npmrc` > user `~/.npmrc`),
+so the publish auth lookup hit the Verdaccio mirror, which has no
+token configured.
+
+Fix:
+1. Drop the `@honest-pitches:registry=...` line from the project
+   `.npmrc`. The SDK has zero `@honest-pitches/*` runtime deps (the
+   "fat SDK" contract), so install needs no scoped-registry
+   override; the npmjs default (set by `Setup Node`) is correct
+   for both install and publish.
+2. Belt-and-suspenders: the publish workflow now passes
+   `--registry https://registry.npmjs.org/` EXPLICITLY on the
+   `pnpm publish` call so any future `.npmrc` drift cannot re-break
+   the publish path.
+3. **Dual-publish**: per the operator's "publish to npmjs, neutronix
+   is OK too" direction, the workflow now publishes the SDK to BOTH
+   npmjs.com (primary, required) and the internal Verdaccio mirror
+   at git.neutronix.com (optional, only attempted when
+   `secrets.NEUTRONIX_NPM_TOKEN` is set). The mirror publish is
+   guarded by `if [ -n "${NEUTRONIX_NPM_TOKEN:-}" ]` so a missing
+   token doesn't fail the workflow. The operator provisions the
+   mirror token at their convenience — until then, the npmjs
+   publish is the canonical artifact.
+4. Auth model change: replaced the deprecated `NODE_AUTH_TOKEN` env
+   (npm warns about it on newer versions) with a per-run
+   `~/.npmrc.auth` file containing each registry's `_authToken`,
+   pointed at via `NPM_CONFIG_USERCONFIG`. This is the standard
+   npm/pnpm multi-registry publish pattern and avoids the legacy
+   env-var deprecation warning.
+
+Regression pins:
+- `scripts/npmrc.contract.test.mjs` (new) — pins the project
+  `.npmrc` against scoped-registry drift
+- `scripts/publish-workflow.contract.test.mjs` — updated to pin
+  dual-registry publish, explicit `--registry` flag, and the new
+  auth model
+
+### README rewrite
+
+The v0.4.5 README read like an internal architecture document —
+"Requires a per-user JWT (obtained via the OAuth flow in
+`@honest-pitches/pitcher-mcp` or minted directly via Appwrite's
+magic-link flow)", "This package is the source of truth for the
+pitcher-facing TablesDB surface", the example used
+`appwriteEndpoint: process.env.APPWRITE_ENDPOINT!`, and the API
+table documented `appwriteQueryEqual` / `appwriteQueryLimit` as "the
+TablesDB query DSL the SDK uses internally". External developers
+installing the SDK don't need to know we use Appwrite / TablesDB
+internally — that's an implementation detail.
+
+The v0.4.6 README:
+- Opens with "What this SDK does" instead of "What backend it talks to"
+- Uses neutral config field names (`endpoint`, `projectId`) with a
+  brief note explaining what the SDK connects to
+- Describes the error hierarchy in terms of what fired and when, not
+  what backend produced the error
+- Adds a single explanatory note that the `appwrite*` prefix on
+  helper exports and the `AppwriteRequestError` class name are
+  "naming artifacts 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." (Renaming the
+  exports would be a breaking API change for any v0.4.x consumer
+  and is not in scope for v0.4.6.)
+- Replaces the misleading "Build: tsup → dist/" with the actual
+  `pnpm build` / `node build.mjs → dist/` command
+- Adds a "TypeScript support" note pointing at the TS2307
+  resolution gotcha documented in `src/index.ts`'s header
+
+All `pnpm test:ci` tests green (56 Vitest + 44 contract tests
+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.3.0] - 2026-06-17
+
+See `CHANGELOG.d/2026-06-17.md` for the change set.
+
+## [0.2.0] - 2026-06-15
+
+Initial extraction from
+`honest-pitches-platform-libs/packages/pitcher-sdk/`
+(where the package was `0.1.0`, `private: true`, and only
+available to other workspace packages). This is the first
+**publishable** release; the `0.1.0` line stays in
+`platform-libs/` as a deprecation stub re-exporting the
+published `0.2.0` artifact.
+
+See `CHANGELOG.d/2026-06-15.md` for the full extraction
+notes.

package/README.md

@@ -0,0 +1,157 @@
+# `@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](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.
+
+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.
+
+## Install
+
+```bash
+npm install @honest-pitches/pitch-sdk
+# or
+pnpm add @honest-pitches/pitch-sdk
+```
+
+The package is published publicly on [npmjs.com](https://www.npmjs.com/package/@honest-pitches/pitch-sdk).
+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.
+
+```ts
+import { createPitcherClient } from "@honest-pitches/pitch-sdk";
+
+// Mint a per-user JWT via your platform OAuth flow, then:
+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
+});
+
+const pitches = await client.pitches.list({ status: "live" });
+```
+
+## API
+
+### Client factory
+
+| Export | Kind | Notes |
+| --- | --- | --- |
+| `createPitcherClient(config)` | factory | builds the client; `initialJwt` is a short-lived per-user JWT, NOT a long-lived API key |
+| `resolvePitcherConfig(config)` | helper | merges defaults with caller-supplied overrides |
+
+### Pitch operations
+
+| Export | Kind | Notes |
+| --- | --- | --- |
+| `PitchesApi` | class | list / get / create / update / transition 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 |
+
+### 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 |
+
+### 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)
+- `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`).
+
+## 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`.
+
+## Build (for SDK maintainers)
+
+```bash
+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.