@marcohefti/request-network-api-contracts 0.5.0 → 0.5.2

package/README.md

@@ -38,14 +38,20 @@ pnpm add -D @marcohefti/request-network-api-contracts
 
 ## Updating the spec
 
-Use the TypeScript client's tooling to refresh the contracts in-place:
+Use the TypeScript client's tooling to refresh the contracts in-place. From the TypeScript client repository, run:
 
 ```bash
-pnpm --filter "./packages/request-api-client" prepare:spec
-pnpm --filter "./packages/request-client-contracts" verify
+pnpm prepare:spec
 ```
 
-`prepare:spec` downloads the latest OpenAPI document into `specs/openapi/`, refreshes metadata, and regenerates the TypeScript/Zod outputs in the client package. Follow with `verify` to sanity-check file sizes and presence before committing updates across both packages.
+This downloads the latest OpenAPI document into the contracts package's `specs/openapi/`, refreshes metadata, and regenerates the TypeScript/Zod outputs. Then verify the contracts package:
+
+```bash
+cd ../request-network-api-contracts
+npm run verify
+```
+
+The `verify` script sanity-checks file sizes and presence before committing updates across both packages.
 
 ## Future work
 

package/docs/OVERVIEW.md

@@ -19,9 +19,9 @@ Git dependency.
 ## Directory Structure
 
 ```
-packages/request-client-contracts/
+.
 ├── README.md
-├── package.json              # workspace metadata (private)
+├── package.json              # package metadata
 ├── specs/
 │   ├── README.md                     # explains generated vs manual assets
 │   ├── openapi/
@@ -41,20 +41,29 @@ packages/request-client-contracts/
 
 ## Consumption Strategy
 
-- **Monorepo:** SDK packages reference files via the workspace package name
-  (`@marcohefti/request-network-api-contracts/specs/...`). Build/validation scripts run from
-  the monorepo root can read from this package without additional tooling.
-- **Post-split:** Each SDK repository will include this repo via Git submodule
-  (or shallow git dependency) so the same files are available without copying.
-  Documentation here will outline the update workflow.
+- **Node / TypeScript SDKs:** Reference files via the published package name
+  (`@marcohefti/request-network-api-contracts/specs/...`) in your build and validation scripts.
+- **Multi-package workspaces:** When this repo is part of a larger workspace,
+  scripts running from the workspace root can still read from the package path above without any special wiring.
+- **Other SDKs:** Non-Node clients can vendor the `specs/**` and `fixtures/**`
+  directories or use this repository as a Git submodule / subtree so the same
+  files are available without copying them by hand.
 
 ## Update Workflow
 
-1. Run `pnpm --filter "./packages/request-api-client" prepare:spec` to download the latest OpenAPI spec and metadata into `specs/openapi/` and regenerate the TypeScript/Zod outputs in the client package.
-2. Update webhook fixtures in `fixtures/webhooks/` when Request publishes new payloads. Pair every new fixture with test coverage in each SDK.
-3. Execute `pnpm --filter "./packages/request-client-contracts" verify` to confirm the expected files are present and within size bounds.
-4. Commit the contract changes (`specs/**`, `fixtures/**`, docs) together with any regenerated client artefacts so consumers can diff the update in one review.
-5. Append an entry to `docs/UPDATES.md` capturing the date, upstream reference, and required SDK follow-up.
+1. Refresh the OpenAPI spec (see `docs/UPDATE-WORKFLOW.md` for details). When
+   you maintain the TypeScript client alongside this package, that typically
+   means running its `pnpm run prepare:spec` task so the latest OpenAPI
+   document and metadata land in `specs/openapi/`.
+2. Update webhook fixtures in `fixtures/webhooks/` when Request publishes new
+   payloads. Pair every new fixture with test coverage in each SDK.
+3. Run `npm run verify` from this repository to confirm the expected files are
+   present and within size bounds.
+4. Commit the contract changes (`specs/**`, `fixtures/**`, docs) together with
+   any regenerated client artefacts so consumers can diff the update in one
+   review.
+5. Append an entry to `docs/UPDATES.md` capturing the date, upstream
+   reference, and required SDK follow-up.
 
 ## Related Backlog Tasks
 

package/docs/PUBLISHING.md

@@ -0,0 +1,81 @@
+# Publishing `@marcohefti/request-network-api-contracts`
+
+This package publishes the shared Request Network REST API contracts to npm so
+SDKs can consume the OpenAPI spec, metadata, and webhook fixtures without
+vendoring files.
+
+Use this checklist when preparing a release.
+
+## Preflight
+
+- [x] `package.json` metadata is correct:
+  - `name: "@marcohefti/request-network-api-contracts"`
+  - `version` bumped according to the changes (0.5.x for the initial public line).
+  - `"private": false` and `"license": "MIT"`.
+  - `"files"` includes `specs`, `fixtures`, `docs`, and `README.md`.
+- [x] `README.md` and `docs/OVERVIEW.md` describe the current contents (OpenAPI,
+      webhooks, fixtures) and how SDKs should consume them.
+- [x] OpenAPI spec and metadata are refreshed via the TypeScript client’s tooling
+      (see `docs/UPDATE-WORKFLOW.md` step 1).
+- [x] Webhook schema (`specs/webhooks/request-network-webhooks.json`) and
+      fixtures under `fixtures/webhooks/**` reflect the latest published webhook
+      events.
+- [x] `node scripts/verify.js` passes to confirm the expected assets exist and
+      are non-empty.
+
+## Release Metadata
+
+- [x] `docs/UPDATES.md` records the latest contract update (date, summary,
+      upstream source, required SDK follow-up).
+- [ ] Tag strategy documented (e.g., `v0.x.y` for contract updates, semantic
+      version bumps when contracts introduce breaking changes for SDKs).
+
+## Publishing Steps (Automated via GitHub Actions)
+
+Publishing is fully automated using GitHub Actions and OIDC trusted publishers. No npm tokens required.
+
+**To publish a new version:**
+
+1. Bump the version using npm:
+   ```bash
+   npm version patch   # for bug fixes (0.5.1 -> 0.5.2)
+   npm version minor   # for new features (0.5.1 -> 0.6.0)
+   npm version major   # for breaking changes (0.5.1 -> 1.0.0)
+   ```
+
+2. Push the tag to GitHub:
+   ```bash
+   git push --follow-tags
+   ```
+
+3. GitHub Actions automatically:
+   - Verifies spec files exist (`node scripts/verify.js`)
+   - Publishes to npm using OIDC authentication
+   - Generates provenance attestations
+
+4. Verify the publish succeeded:
+   - Check GitHub Actions: https://github.com/marcohefti/request-network-api-contracts/actions
+   - Check npm: https://www.npmjs.com/package/@marcohefti/request-network-api-contracts
+
+**Prerequisites:**
+- Trusted publisher configured on npmjs.com (already set up)
+- Workflow file exists: `.github/workflows/publish.yml`
+- Repository uses npm 11.5.1+ in CI
+
+**Manual publish (emergency only):**
+If GitHub Actions is unavailable, you can publish manually:
+```bash
+npm login
+npm publish --access public
+```
+
+## Post-Release
+
+- [ ] Update TypeScript and PHP clients (and any other SDKs) to depend on the
+      new version.
+- [ ] Run their spec/fixture sync scripts and parity guards:
+  - TS: `pnpm run prepare:spec` + tests.
+  - PHP: `composer update:spec`, `composer parity:openapi`, `composer parity:webhooks`.
+- [ ] Record any required client follow-up work in the relevant SDK
+      repositories or your own release notes so consumers know which client
+      versions pick up the new contracts.

package/docs/UPDATE-WORKFLOW.md

@@ -4,11 +4,14 @@ Use this checklist whenever the Request Network API publishes contract changes.
 
 ## 1. Refresh the OpenAPI spec
 
-```bash
-pnpm --filter "./packages/request-api-client" prepare:spec
-```
-
-`prepare:spec` downloads the latest OpenAPI document into `specs/openapi/` (updating both the JSON and `.meta.json`) and regenerates the TypeScript + Zod outputs referenced by the client.
+- If you maintain the official TypeScript client alongside this package, run its
+  `pnpm run prepare:spec` task to download the latest OpenAPI document and
+  regenerate the generated types. That tooling is responsible for writing
+  `specs/openapi/request-network-openapi.json` and the corresponding
+  `.meta.json` file into this package.
+- If you are only using this repository, fetch the OpenAPI document directly
+  from the upstream Request API (`https://api.request.network/open-api/openapi.json`)
+  and update both the JSON and `.meta.json` files under `specs/openapi/`.
 
 ## 2. Update webhook schema (if needed)
 
@@ -22,11 +25,14 @@ pnpm --filter "./packages/request-api-client" prepare:spec
 
 ## 4. Verify assets
 
+From this repository, run:
+
 ```bash
-pnpm --filter "./packages/request-client-contracts" verify
+npm run verify
 ```
 
-The verification script asserts that the expected files exist and logs their sizes for a quick sanity check.
+The verification script asserts that the expected files exist and logs their
+sizes for a quick sanity check.
 
 ## 5. Document and commit
 

package/docs/UPDATES.md

@@ -12,4 +12,4 @@ change so SDK maintainers know when to regenerate code.
 -	**Notes:** Regeneration impact, required SDK updates, new fixtures
 
 ## History
-- *No entries yet* - initial import seeded via `pnpm --filter "./packages/request-api-client" prepare:spec` on 2025-11-06.
+- *No entries yet* - initial import seeded via the TypeScript client’s `pnpm run prepare:spec` tooling on 2025-11-06.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcohefti/request-network-api-contracts",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "private": false,
   "description": "Shared contracts for Request Network API clients (OpenAPI spec, webhook fixtures).",
   "license": "MIT",

package/specs/README.md

@@ -13,7 +13,10 @@ webhooks/  # manually curated webhook schema
 - `request-network-openapi.meta.json` – metadata captured during fetch (e.g.
   etag, timestamp, source URL).
 
-These files should only change through the regeneration script (`pnpm --filter "./packages/request-api-client" fetch:openapi` or the broader `prepare:spec`). Avoid manual edits. Rerun the fetch command when upstream changes land and commit the updated JSON + metadata.
+These files should only change through the regeneration tooling in your SDKs
+(for example, the TypeScript client’s `pnpm run fetch:openapi` or broader
+`pnpm run prepare:spec` commands). Avoid manual edits. Rerun the fetch command
+when upstream changes land and commit the updated JSON + metadata.
 
 ## `webhooks/`
 - `request-network-webhooks.json` – maintained manually. Update it when webhook

package/specs/openapi/request-network-openapi.meta.json

@@ -1,6 +1,6 @@
 {
   "url": "https://api.request.network/open-api/openapi.json",
-  "fetchedAt": "2025-12-11T02:53:19.867Z",
+  "fetchedAt": "2025-12-11T03:04:31.072Z",
   "etag": null,
   "lastModified": null
 }