@incomy/platform-sdk 0.4.0-beta.1973 → 0.5.0-beta.2075

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/dist/services/hub/index.d.ts

@@ -77,6 +77,8 @@ export type { TemplatePaginatedList } from './models/TemplatePaginatedList';
 export type { UpdateProfileRequest } from './models/UpdateProfileRequest';
 export type { User } from './models/User';
 export type { UserIdentity } from './models/UserIdentity';
+export type { UserSettings } from './models/UserSettings';
+export type { UserSettingsEdit } from './models/UserSettingsEdit';
 export type { WalletBalance } from './models/WalletBalance';
 export type { WalletBalancePaginatedList } from './models/WalletBalancePaginatedList';
 export { AccrualsService } from './services/AccrualsService';
@@ -91,3 +93,4 @@ export { OperationsService } from './services/OperationsService';
 export { ProjectsService } from './services/ProjectsService';
 export { ProjectWalletsService } from './services/ProjectWalletsService';
 export { TemplatesService } from './services/TemplatesService';
+export { UserSettingsService } from './services/UserSettingsService';

package/dist/services/hub/index.js

@@ -17,3 +17,4 @@ export { OperationsService } from './services/OperationsService';
 export { ProjectsService } from './services/ProjectsService';
 export { ProjectWalletsService } from './services/ProjectWalletsService';
 export { TemplatesService } from './services/TemplatesService';
+export { UserSettingsService } from './services/UserSettingsService';

package/dist/services/hub/models/Accrual.d.ts

@@ -2,6 +2,7 @@ import type { BucketBreakdown } from './BucketBreakdown';
 import type { Money } from './Money';
 export type Accrual = {
     bucketBreakdown?: Array<BucketBreakdown> | null;
+    companyId?: string | null;
     /**
      * If set, record will be deleted when unlined from a multievent or when linked multievent is deleted.
      */

package/dist/services/hub/models/AccrualEdit.d.ts

@@ -2,6 +2,10 @@ import type { BucketBreakdown } from './BucketBreakdown';
 import type { Money } from './Money';
 export type AccrualEdit = {
     bucketBreakdown?: Array<BucketBreakdown> | null;
+    /**
+     * Set to "" in order to clear.
+     */
+    companyId?: string | null;
     /**
      * If set, record will be deleted when unlined from a multievent or when linked multievent is deleted.
      */

package/dist/services/hub/models/AccrualInsert.d.ts

@@ -2,6 +2,7 @@ import type { BucketBreakdown } from './BucketBreakdown';
 import type { Money } from './Money';
 export type AccrualInsert = {
     bucketBreakdown?: Array<BucketBreakdown> | null;
+    companyId?: string | null;
     /**
      * If set, record will be deleted when unlined from a multievent or when linked multievent is deleted.
      */

package/dist/services/hub/models/LogAccrual.d.ts

@@ -4,6 +4,7 @@ import type { Money } from './Money';
 export type LogAccrual = {
     balance?: BalanceReport;
     bucketBreakdown?: Array<BucketBreakdown> | null;
+    companyId?: string | null;
     /**
      * If set, record will be deleted when unlined from a multievent or when linked multievent is deleted.
      */

package/dist/services/hub/models/LogOperation.d.ts

@@ -13,7 +13,9 @@ export type LogOperation = {
     money: Money;
     multiEventId?: string | null;
     name: string;
+    originCompanyId?: string | null;
     originWalletId?: string | null;
+    targetCompanyId?: string | null;
     targetWalletId?: string | null;
     time: string;
     type: 'in' | 'out' | 'transfer';

package/dist/services/hub/models/Operation.d.ts

@@ -11,7 +11,9 @@ export type Operation = {
     money: Money;
     multiEventId?: string | null;
     name: string;
+    originCompanyId?: string | null;
     originWalletId?: string | null;
+    targetCompanyId?: string | null;
     targetWalletId?: string | null;
     time: string;
     type: 'in' | 'out' | 'transfer';

package/dist/services/hub/models/OperationEdit.d.ts

@@ -13,10 +13,18 @@ export type OperationEdit = {
      */
     multiEventId?: string | null;
     name?: string | null;
+    /**
+     * Set to "" in order to clear.
+     */
+    originCompanyId?: string | null;
     /**
      * Set to "" in order to clear.
      */
     originWalletId?: string | null;
+    /**
+     * Set to "" in order to clear.
+     */
+    targetCompanyId?: string | null;
     /**
      * Set to "" in order to clear.
      */

package/dist/services/hub/models/OperationInsert.d.ts

@@ -10,7 +10,9 @@ export type OperationInsert = {
     money: Money;
     multiEventId?: string | null;
     name: string;
+    originCompanyId?: string | null;
     originWalletId?: string | null;
+    targetCompanyId?: string | null;
     targetWalletId?: string | null;
     /**
      * MultiEvent time will be used if left empty

package/dist/services/hub/models/UpdateProfileRequest.d.ts

@@ -1,8 +1,4 @@
 export type UpdateProfileRequest = {
     firstName?: string | null;
-    /**
-     * Preferred UI language as a lowercase ISO 639-1 code. Only the supported locales are accepted.
-     */
-    language?: string | null;
     lastName?: string | null;
 };

package/dist/services/hub/models/User.d.ts

@@ -5,11 +5,6 @@ export type User = {
     firstName?: string | null;
     id?: string;
     identities?: Array<UserIdentity> | null;
-    /**
-     * Preferred UI language as a lowercase ISO 639-1 code (e.g. "en", "pl").
-     * Null means the user has not chosen one; the client falls back to the browser language.
-     */
-    language?: string | null;
     lastName?: string | null;
     readonly name?: string | null;
 };

package/dist/services/hub/models/UserIdentity.d.ts

@@ -1,10 +1,14 @@
 export type UserIdentity = {
-    auth0Id: string | null;
     avatar?: string | null;
     email?: string | null;
     firstName?: string | null;
+    /**
+     * Surrogate identifier of this identity link. Stable across logins and used to address the
+     * identity (e.g. when unlinking). The raw external subject is intentionally not exposed.
+     */
+    id?: string;
     isCurrent?: boolean;
     lastName?: string | null;
-    readonly provider?: string | null;
+    provider: string | null;
     readonly providerDisplayName?: string | null;
 };

package/dist/services/hub/models/UserSettings.d.ts

@@ -0,0 +1,4 @@
+export type UserSettings = {
+    language?: string | null;
+    timezone?: string | null;
+};

package/dist/services/hub/models/UserSettings.js

@@ -0,0 +1 @@
+export {};

package/dist/services/hub/models/UserSettingsEdit.d.ts

@@ -0,0 +1,4 @@
+export type UserSettingsEdit = {
+    language?: string | null;
+    timezone?: string | null;
+};

package/dist/services/hub/models/UserSettingsEdit.js

@@ -0,0 +1 @@
+export {};

package/dist/services/hub/services/AuthService.d.ts

@@ -3,11 +3,11 @@ import type { User } from '../models/User';
 import type { CancelablePromise } from '../core/CancelablePromise';
 export declare class AuthService {
     /**
-     * @param auth0IdToUnlink
+     * @param identityId
      * @returns any OK
      * @throws ApiError
      */
-    static postAuthIdentitiesUnlink(auth0IdToUnlink: string): CancelablePromise<any>;
+    static postAuthIdentitiesUnlink(identityId: string): CancelablePromise<any>;
     /**
      * @param returnUrl
      * @returns any OK

package/dist/services/hub/services/AuthService.js

@@ -2,16 +2,16 @@ import { OpenAPI } from '../core/OpenAPI';
 import { request as __request } from '../core/request';
 export class AuthService {
     /**
-     * @param auth0IdToUnlink
+     * @param identityId
      * @returns any OK
      * @throws ApiError
      */
-    static postAuthIdentitiesUnlink(auth0IdToUnlink) {
+    static postAuthIdentitiesUnlink(identityId) {
         return __request(OpenAPI, {
             method: 'POST',
-            url: '/auth/identities/{auth0IdToUnlink}/unlink',
+            url: '/auth/identities/{identityId}/unlink',
             path: {
-                'auth0IdToUnlink': auth0IdToUnlink,
+                'identityId': identityId,
             },
         });
     }

package/dist/services/hub/services/UserSettingsService.d.ts

@@ -0,0 +1,16 @@
+import type { UserSettings } from '../models/UserSettings';
+import type { UserSettingsEdit } from '../models/UserSettingsEdit';
+import type { CancelablePromise } from '../core/CancelablePromise';
+export declare class UserSettingsService {
+    /**
+     * @returns UserSettings OK
+     * @throws ApiError
+     */
+    static getUsersMeSettings(): CancelablePromise<UserSettings>;
+    /**
+     * @param requestBody
+     * @returns UserSettings OK
+     * @throws ApiError
+     */
+    static patchUsersMeSettings(requestBody?: UserSettingsEdit): CancelablePromise<UserSettings>;
+}

package/dist/services/hub/services/UserSettingsService.js

@@ -0,0 +1,27 @@
+import { OpenAPI } from '../core/OpenAPI';
+import { request as __request } from '../core/request';
+export class UserSettingsService {
+    /**
+     * @returns UserSettings OK
+     * @throws ApiError
+     */
+    static getUsersMeSettings() {
+        return __request(OpenAPI, {
+            method: 'GET',
+            url: '/users/me/settings',
+        });
+    }
+    /**
+     * @param requestBody
+     * @returns UserSettings OK
+     * @throws ApiError
+     */
+    static patchUsersMeSettings(requestBody) {
+        return __request(OpenAPI, {
+            method: 'PATCH',
+            url: '/users/me/settings',
+            body: requestBody,
+            mediaType: 'application/json',
+        });
+    }
+}

package/meta.json

@@ -1,11 +1,11 @@
 {
-  "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.5.0-beta.2075",
+  "generatedAt": "2026-06-28T14:57:47.783Z",
+  "apiCommit": "ff9810a6",
+  "pipelineUrl": "https://gitlab.com/incomy/platform/-/pipelines/2635127130",
   "sources": {
     "hub": {
-      "sha256": "db56e9ea7e70f27b4681ff0437208f90663024ce412985e3edf06463f46eea70"
+      "sha256": "f34d7a263e1fadb8f8b8caad8fed7d6edf3d69e27767e4e737f8b9bee71055b5"
     }
   }
 }

package/package.json

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