@incomy/platform-sdk 0.4.0-beta.1973 → 0.4.0-beta.2001

package/README.md

@@ -0,0 +1,168 @@
+# @incomy/platform-sdk
+
+Auto-generated TypeScript client for the Incomy platform APIs (currently **Hub**),
+produced from each service's OpenAPI spec and published to npm. Consumed by the
+`web` frontend as `import { hub } from "@incomy/platform-sdk"`.
+
+## TL;DR
+
+- **Daily work:** just merge to `develop` — a beta is published automatically. You don't touch versions.
+- **Release:** `npm version <patch|minor|major>` → commit → **merge to `main`**. No git tags.
+- **Changed the API?** run `npm run snapshot` and commit `oas/hub.json` together with your backend change (otherwise CI fails).
+
+---
+
+## What lives here
+
+| Path | Tracked? | What it is |
+|---|---|---|
+| `package.json` | ✅ committed | npm manifest; the `version` field is the **release base** (the single human knob) |
+| `tsconfig.json` | ✅ committed | TypeScript build config |
+| `package-lock.json` | ✅ committed | pinned build deps (`npm ci` in CI) |
+| `scripts/*.mjs` | ✅ committed | generation / snapshot / contract-gate logic |
+| `oas/hub.json` | ✅ committed | **OpenAPI contract snapshot** (reviewable in PRs, drives generation) |
+| `generate.sh` | ✅ committed | local one-shot build (starts the API, then runs the generator) |
+| `services/`, `dist/`, `index.ts`, `meta.json`, `*.tgz`, `node_modules/` | ❌ generated | build output (git-ignored) |
+
+---
+
+## How generation works
+
+There is **one source of truth** for generation: [`scripts/build.mjs`](scripts/build.mjs). CI and
+`generate.sh` both call it — there is no duplicated codegen logic.
+
+It does, in order:
+
+1. Resolve OpenAPI specs from `OAS_SOURCES` (pipe-delimited `name|url-or-path` lines; GitLab
+   package URLs get the `JOB-TOKEN` automatically). With no `OAS_SOURCES`, it reuses the committed
+   `oas/*.json` snapshot — so you can regenerate offline.
+2. Run `openapi-typescript-codegen` per service into `services/<name>` (fetch client, union types).
+3. Write `index.ts` — one namespace export per service: `export * as hub from "./services/hub"`.
+   **This is the public API surface** and it does not change across regenerations.
+4. Stamp the version (when given), write `meta.json` provenance, compile with `tsc`, `npm pack`.
+
+`meta.json` records where the build came from — `sdkVersion`, `apiCommit`, and a sha256 of each
+source spec — so you can always tell which backend commit an SDK build was generated from.
+
+---
+
+## Versioning
+
+The **base** `major.minor.patch` is the `version` field in `package.json` (e.g. `0.4.0`). That is
+the only thing a human sets. CI derives the actual published version from the branch
+([`calculate_version`](.gitlab-ci.yml)):
+
+| Context | Published version |
+|---|---|
+| `main` | `BASE` — clean release, e.g. `0.4.0` |
+| `develop` | `BASE-beta.<pipeline-iid>` — e.g. `0.4.0-beta.207` |
+| `feature/*` (build only) | `BASE-alpha.<pipeline-iid>` |
+
+`CI_PIPELINE_IID` is strictly increasing per project, so prerelease numbers are always unique and
+monotonic — no duplicate-version publishes.
+
+---
+
+## Releasing (version-file-driven, no tags)
+
+A release happens when a **new base version lands on `main`**. There are no manual git tags.
+
+| Context | Publishes? | dist-tag | Notes |
+|---|:---:|---|---|
+| `feature/*` | ❌ (build/validate only) | — | proves the SDK still compiles |
+| `develop` | ✅ every push | `@beta` | continuous betas for testing |
+| `main` | ✅ **only if the version is new** | `@latest` | the clean release |
+
+The `main` job is **idempotent**: it checks `npm view "<name>@<version>"` and skips if that version
+is already published. So a `main` merge that didn't bump the version is a no-op, and pipeline
+retries never double-publish. `@latest` therefore only ever moves to a clean version from `main`.
+
+### How to cut a release
+
+```bash
+cd sdk
+npm version minor --no-git-tag-version   # bump the base in package.json (see "which level" below)
+git commit -am "chore(sdk): release 0.5.0"
+# open an MR and merge to main  →  CI publishes 0.5.0 to @latest
+```
+
+(Or use the VS Code task **`sdk: bump version (release)`** for the bump step.)
+
+### Which level to bump (semver)
+
+| Level | When | Example |
+|---|---|---|
+| **patch** | bug fix, **API contract unchanged** | `0.4.0 → 0.4.1` |
+| **minor** | new, backward-compatible API (new endpoint / optional field) | `0.4.0 → 0.5.0` |
+| **major** | breaking change (removed/renamed/retyped field, removed endpoint) | `0.4.0 → 1.0.0` |
+
+The `oas/hub.json` diff tells you the level: `path/schema added` or a new optional field → **minor**;
+`path removed` or an incompatible `schema modified` → **major**; no `oas` change at all → **patch**.
+
+> Pre-1.0 note: while on `0.x`, breaking changes conventionally go out as a **minor** bump; reserve
+> `1.0.0` for the first explicitly-stable API.
+
+---
+
+## The OpenAPI contract snapshot + gate
+
+`oas/hub.json` is a committed, normalized copy of the Hub OpenAPI spec — the **API contract** the
+SDK is generated from. Committing it means any API change shows up as a reviewable diff in the PR.
+
+A CI gate (`check_swagger_snapshot` in
+[`services/hub/.gitlab-ci.yml`](../services/hub/.gitlab-ci.yml)) re-exports the spec from the
+current backend and **fails if it differs from the committed snapshot** — so an API change can't
+slip through without updating the contract. The `servers` block (derived from `INCOMY_ROOT_DOMAIN`)
+is ignored, so deployment-environment differences don't cause false failures.
+
+**When you change the API**, refresh and commit the snapshot alongside your backend change:
+
+```bash
+cd sdk
+npm run snapshot        # re-export from the local API on :20001 → oas/hub.json
+git add oas/hub.json    # commit it together with the C# change
+```
+
+(VS Code task: **`sdk: snapshot OAS contract`**. Start the API first via **`run hub api with db`**.)
+
+---
+
+## Local development
+
+| Command (in `sdk/`) | What it does | Needs API running? |
+|---|---|---|
+| `./generate.sh` | full local build: starts hub-api via Docker, then generates from the live spec | starts it for you |
+| `npm run generate` | regenerate from the committed `oas/hub.json` snapshot | no |
+| `npm run snapshot` | refresh `oas/hub.json` from the live API (`:20001`) | yes |
+| `npm run build` | just `tsc` | no |
+
+To test changes against `web`, build here and overwrite `web/node_modules/@incomy/platform-sdk`
+with the resulting `dist/`.
+
+---
+
+## Consuming the SDK
+
+```bash
+npm install @incomy/platform-sdk          # @latest → newest clean release
+npm install @incomy/platform-sdk@beta     # newest beta (pre-release testing)
+```
+
+```ts
+import { hub } from "@incomy/platform-sdk";
+// hub.<Service>.<operation>(...)
+```
+
+Pin an exact version (recommended for a generated client) and bump deliberately. Avoid caret ranges
+on prereleases (e.g. `^0.4.0-189`) — npm prerelease range semantics make them surprising.
+
+---
+
+## Gotchas
+
+- **A `main` merge without a version bump publishes nothing** (idempotent skip). To release, bump first.
+- **Keep `version` a clean `X.Y.Z`** — never hand-add `-beta`/`-alpha`; CI adds those.
+- **npm versions are immutable** — you can't unpublish a mistake; fix forward with a higher version
+  (and `npm dist-tag` if you need to move `@latest` back).
+- **`main` also deploys the backend.** A bump-and-merge releases the SDK *and* deploys the API
+  together; a no-bump merge just deploys the API.

package/meta.json

@@ -1,8 +1,8 @@
 {
-  "sdkVersion": "0.4.0-beta.1973",
-  "generatedAt": "2026-06-25T17:05:16.389Z",
-  "apiCommit": "cfa90784",
-  "pipelineUrl": "https://gitlab.com/incomy/platform/-/pipelines/2629786412",
+  "sdkVersion": "0.4.0-beta.2001",
+  "generatedAt": "2026-06-26T21:06:05.155Z",
+  "apiCommit": "4f2a29d7",
+  "pipelineUrl": "https://gitlab.com/incomy/platform/-/pipelines/2632900221",
   "sources": {
     "hub": {
       "sha256": "db56e9ea7e70f27b4681ff0437208f90663024ce412985e3edf06463f46eea70"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@incomy/platform-sdk",
-  "version": "0.4.0-beta.1973",
+  "version": "0.4.0-beta.2001",
   "private": false,
   "type": "module",
   "files": [