@icib.dev/api-client 1.0.1 → 1.0.3

package/README.md

@@ -21,23 +21,41 @@ const res = await apiClient.allegati.list({ page: 1, size: 10 });
 const detail = await apiClient.allegati.read({ id: res.data.results[0].id });
 ```
 
-## API Client Generator (for maintainers)
+## API Client Generator
 
-To regenerate the client from the OpenAPI spec:
+To regenerate the client from the OpenAPI spec.
+
+### From consuming apps (npx)
+
+If you use this library in your app, run the generator from your project root:
 
 ```bash
-npm run generate
+npx api-client-generate
 ```
 
 With options:
 
 ```bash
-npm run generate -- --url https://api.icib.dev/docs/?format=openapi --out api
+# Custom URL
+npx api-client-generate --url https://api.example.com/docs/openapi --out api
+
+# Using BASE_URL env (default: $BASE_URL/docs/openapi)
+BASE_URL=https://api.example.com npx api-client-generate --out api
 ```
 
+The client is generated in your project directory (e.g. `./api/`).
+
+### From the library repo (maintainers)
+
+```bash
+npm run generate
+```
+
+By default, the spec URL is `$BASE_URL/docs/openapi` when the `BASE_URL` env variable is set. If unset, it falls back to the ICIB default.
+
 ### Output
 
-The generator creates an `api/` folder:
+The generator creates an `api/` folder and a local manifest (`api-client.manifest.json`, gitignored):
 
 ```
 api/
@@ -50,6 +68,22 @@ api/
 └── index.ts           # Re-exports all contexts and types
 ```
 
+### Hash verification
+
+The build verifies that the generated client matches the current OpenAPI docs. When you run `npm run build`, it:
+
+1. Reads the manifest (created by `generate`)
+2. Fetches the current docs and compares their hash
+3. Hashes the generated client files and compares with the manifest
+
+**If docs changed:** Build fails with:
+> API docs have changed. Run `npm run generate` to regenerate the client, then update your application.
+
+**If client was manually edited:** Build fails with:
+> Generated client files were modified. Run `npm run generate` to regenerate.
+
+**If manifest is missing:** Run `npm run generate` first (e.g. after a fresh clone).
+
 ### JSDoc documentation
 
 The generated client includes JSDoc comments from the OpenAPI spec:
@@ -77,13 +111,3 @@ await apiClient.QR_Code.generateCsv(
   { download: true, filename: "qrcodes.csv" },
 );
 ```
-
-## Publishing
-
-To publish to npm under the `@icib.dev` scope:
-
-1. Ensure you're logged in: `npm login`
-2. Create the org if needed: `npm org create icib.dev` (or add your user to it)
-3. Publish: `npm publish --access public`
-
-The `prepublishOnly` script will automatically run `generate` and `build` before publishing.