@arbol-ai/sdk 1.20261019.4056 → 2.1.0

package/README.md

@@ -3,8 +3,9 @@
 The Arbol API for TypeScript and JavaScript, generated by
 [Cloudflare Forge](https://github.com/cloudflare/forge) from the platform's public OpenAPI,
 [`https://api.getarbol.com/openapi.json`](https://api.getarbol.com/openapi.json). Everything in `src/`
-is Forge's TypeScript output, unedited, and the package's version is the API release it was generated
-from (`1.YYYYMMDD.n`).
+is Forge's TypeScript output, unedited. Versions are semver, and each one records the OpenAPI it was
+generated from: `npm view @arbol-ai/sdk@<version> arbol.openapi` prints its `release` (`info.version`)
+and content hash (`sha256`).
 
 ```sh
 npm install @arbol-ai/sdk
@@ -56,49 +57,63 @@ The server authorizes every call: a method in the client is not a grant.
 bun install
 bun run forge       # build the pinned Cloudflare Forge with cargo into .forge/ (once; needs Rust)
 bun run openapi     # download https://api.getarbol.com/openapi.json
-bun run generate    # src/ from openapi.json with `forge --target ts`; the version from its info.version
+bun run generate    # src/ from openapi.json with `forge --target ts`; its release and hash in arbol.openapi
 bun run hash        # the OpenAPI's content hash (see Releases)
 bun run verify      # typecheck and build dist/
 ```
 
-`openapi.json` is downloaded at generation time and not committed; `package.json`'s version is the
-OpenAPI version `src/` was generated from, and `release.json` records that version and the OpenAPI's
-content hash. Forge is pinned to its commit
+`openapi.json` is downloaded at generation time and not committed. `package.json`'s `arbol.openapi`
+records the OpenAPI `src/` was generated from, its `info.version` as `release` and its content hash as
+`sha256`; `version` and `arbol` are release metadata the workflows set. Forge is pinned to its commit
 `7f86447210b7bea3779bfdab3cd5655eade0eadb` (0.1.0) in the `forge` script.
 
 ## Releases
 
-Releases are automatic, from the API down to the CLI:
+Versions are semver, independent of the OpenAPI's release number. The 1.x versions (`1.YYYYMMDD.n`)
+were the OpenAPI's date releases; 2.x starts at 2.1.0.
+
+Releases of a new OpenAPI are automatic, from the API down to the CLI:
 
 1. **Gateway.** When the Arbol API ships an OpenAPI release, the gateway sends this repository a
    `repository_dispatch` `openapi-release` with `{ "version": "<release>" }`.
 2. **SDK (this repository).** [Generate](.github/workflows/generate.yml) runs on that dispatch, every
    six hours, and by hand. It downloads the OpenAPI (waiting until the API serves the announced release)
-   and hashes its content. When the hash differs from the one in `release.json`, it regenerates `src/`
-   with Forge, verifies it, commits `Release <version>` to `main` as Arbol, and publishes
-   `@arbol-ai/sdk` to npm with [Publish](.github/workflows/publish.yml), with a provenance statement.
-3. **CLI.** After publishing, Generate sends
+   and hashes its content. When the hash differs from `arbol.openapi.sha256` in `package.json`, it
+   regenerates `src/` with Forge, records the OpenAPI in `arbol.openapi`, and takes the highest version
+   on npm with the minor raised and the patch at 0 (2.1.0, 2.2.0, 2.3.0, …). It verifies the result,
+   commits `Release <version>` to `main` as Arbol, and publishes `@arbol-ai/sdk` to npm with
+   [Publish](.github/workflows/publish.yml), with a provenance statement.
+3. **CLI.** After publishing, Publish sends
    [project-arbol-cli](https://github.com/getarbol/project-arbol-cli) a `repository_dispatch`
-   `sdk-release` with `{ "version": "<published version>", "sha256": "<OpenAPI hash>" }`, and the CLI
-   releases itself on it.
+   `sdk-release` with `{ "version": "<published version>", "openapi": { "release": "…", "sha256": "…" } }`,
+   the published `version` and `arbol.openapi`, and the CLI releases itself on it.
 
 The hash ([`scripts/release.ts`](scripts/release.ts)) is the SHA-256 hex of the OpenAPI's canonical
 JSON (object keys sorted recursively, arrays in order, no whitespace) with `info.version` removed. A new
-release number with an identical API hashes the same, so it commits, publishes, and announces nothing.
-A version on `main` that is not on npm yet, such as one a failed run left behind, is published by the
-next run.
+release number with an identical API hashes the same, so Generate commits, publishes, and announces
+nothing. A version on `main` that is not on npm yet, such as one a failed run left behind, is published
+by the next run.
+
+Changes to the SDK itself, such as a new Forge pin, are released by hand: commit them to `main`
+(regenerated with `bun run generate` when they change `src/`), then run Publish on `main` with `bump`
+`patch` (the default), `minor` or `major`:
+
+```sh
+gh workflow run publish.yml --repo getarbol/project-arbol-sdk-js --ref main -f bump=patch
+```
 
-Changes outside the OpenAPI, such as a new Forge pin, release nothing on their own: they ship with the
-next OpenAPI change.
+It raises that part of the highest version on npm (while no 2.x version is published, the result is
+2.1.0 whatever the bump), commits `Release <version>` to `main`, publishes it, and announces it to the
+CLI like Generate. It refuses when `main`'s version is not on npm yet (run Generate, which publishes it),
+and when nothing that goes into the package (`src/`, `package.json`, `tsconfig.json`, `bun.lock`,
+`README.md`, `LICENSE`) changed since the commit that released `main`'s version, so the same SDK is
+never published twice. A manual release and Generate wait for each other.
 
-Generate pushes and dispatches as the Arbol Bot GitHub App, so its commit to `main` runs
-[Verify](.github/workflows/verify.yml). It needs the organization variable `ARBOL_BOT_APP_ID`, the
+Generate and Publish push and dispatch as the Arbol Bot GitHub App, so their commits to `main` run
+[Verify](.github/workflows/verify.yml). They need the organization variable `ARBOL_BOT_APP_ID`, the
 organization secret `ARBOL_BOT_PRIVATE_KEY`, and the App installed with contents write access to this
 repository and project-arbol-cli. npm publishing uses the organization secret `NPM_TOKEN`.
 
-Run Publish by hand on `main` to publish the version in `package.json`; a version that is already on npm
-is left untouched.
-
 ## License
 
 [Apache License 2.0](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbol-ai/sdk",
-  "version": "1.20261019.4056",
+  "version": "2.1.0",
   "description": "The Arbol API for TypeScript and JavaScript, generated by Cloudflare Forge from the platform's public OpenAPI.",
   "keywords": [
     "arbol",
@@ -39,7 +39,7 @@
     "forge": "cargo install --quiet --locked --git https://github.com/cloudflare/forge --rev 7f86447210b7bea3779bfdab3cd5655eade0eadb --root .forge forge",
     "openapi": "curl -fsS --proto =https --max-redirs 0 --max-filesize 33554432 -o openapi.json https://api.getarbol.com/openapi.json",
     "hash": "bun scripts/release.ts hash",
-    "generate": "rm -rf src && .forge/bin/forge --target ts --out src openapi.json && bun pm pkg set version=\"$(jq -r .info.version openapi.json)\" && bun scripts/release.ts record",
+    "generate": "rm -rf src && .forge/bin/forge --target ts --out src openapi.json && bun scripts/release.ts record",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build": "rm -rf dist && tsc -p tsconfig.json",
     "verify": "bun run typecheck && bun run build"
@@ -47,5 +47,11 @@
   "devDependencies": {
     "typescript": "7.0.2"
   },
-  "packageManager": "bun@1.4.3"
+  "packageManager": "bun@1.4.3",
+  "arbol": {
+    "openapi": {
+      "release": "1.20261019.4056",
+      "sha256": "a160f98ddd0944d6e78111d113869b22cac6caabc036bb47f7609c009c37e501"
+    }
+  }
 }