@camunda8/hub-public-api-client 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# @camunda8/hub-public-api-client
+
+A typed TypeScript client for the **Camunda Web Modeler (Hub) public API v2**.
+
+The client is generated from the OpenAPI specification that lives at
+[`restapi/public-api/src/main/resources/openapi/v2`](../../../restapi/public-api/src/main/resources/openapi/v2),
+which is the single source of truth for the public API contract. TypeScript
+consumers get typed request/response models and typed methods instead of
+hand-written types that can drift from the published contract.
+
+It is built on:
+
+- [`openapi-typescript`](https://openapi-ts.dev/) — generates the type
+  definitions (`src/generated/schema.ts`) from the spec.
+- [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/) — a tiny, typed
+  `fetch` wrapper used at runtime.
+
+## Installation
+
+```bash
+npm install @camunda8/hub-public-api-client
+```
+
+## Usage
+
+Create a client with the API base URL (including the `/api/v2` segment) and a
+bearer token, then call endpoints by path and method. Request bodies, query
+parameters, path parameters, and responses are all fully typed from the spec.
+
+```ts
+import { createHubPublicApiClient } from '@camunda8/hub-public-api-client';
+
+const client = createHubPublicApiClient({
+  baseUrl: 'https://modeler.camunda.io/api/v2',
+  // A static token, or a (possibly async) function returning a fresh one.
+  token: async () => fetchAccessToken()
+});
+
+// Typed path + body. `data` is the typed response, `error` the typed problem detail.
+const { data, error } = await client.POST('/projects', {
+  body: { name: 'My project', workspaceKey: 'my-workspace-key' }
+});
+
+if (error) {
+  throw new Error(`Request failed: ${error.detail}`);
+}
+
+console.log(data.projectKey);
+
+// Path parameters are typed too. Every call returns `{ data, error }`.
+const { data: project } = await client.GET('/projects/{projectKey}', {
+  params: { path: { projectKey: data.projectKey } }
+});
+```
+
+### Authentication
+
+`token` may be a string or a function returning a string (sync or async). When
+provided, an `Authorization: Bearer <token>` header is attached to every
+request. The function form is resolved on each request, so it can return a
+freshly refreshed token. Omit `token` to handle authentication yourself (e.g.
+via a custom `fetch` or default `headers`, both forwarded to `openapi-fetch`).
+
+### Using the model types
+
+The generated models are exported for reuse in your own code:
+
+```ts
+import type { Schemas } from '@camunda8/hub-public-api-client';
+
+type Project = Schemas['ProjectResult'];
+```
+
+The lower-level `paths`, `operations`, and `components` types are also exported
+for advanced use cases.
+
+## Generating the client
+
+The generated output (`src/generated/schema.ts`) is **not committed** — it is a
+build artifact produced from the spec at build time (the same way the Java
+models are generated into `target/`). It is gitignored and regenerated
+automatically before `tsc` and `build`, so you normally don't run it by hand.
+To generate it explicitly (e.g. for IDE type-checking right after a fresh
+clone):
+
+```bash
+# From this package directory
+npm run generate
+
+# Or, from the repository root
+make generate-public-api-client
+```
+
+> **Do not edit the generated output by hand.** Change the spec under
+> `restapi/public-api/src/main/resources/openapi/v2` and regenerate.
+
+Published npm consumers never generate anything — they receive the compiled
+`dist/` (built by `prepack`), which already excludes the generated source.
+
+## Staying in sync with the spec
+
+Because the client is regenerated on every build, it can never be stale. The
+[`public-api-client-check`](../../../.github/workflows/public-api-client-check.yml)
+GitHub Actions workflow runs on every pull request that touches the spec or this
+package and **regenerates the client and fails if the current spec no longer
+produces a valid, lint-clean, compiling client** — surfacing breaking contract
+changes at build time. (A dedicated workflow is required because the spec lives
+under `restapi/`, outside the frontend workspace, so turbo's `--affected`
+filtering would not otherwise rebuild the client on a spec-only change.)
+
+You can run the same check locally:
+
+```bash
+make check-public-api-client
+```
+
+## Scripts
+
+| Script             | Description                                                       |
+| ------------------ | ----------------------------------------------------------------- |
+| `npm run generate` | Regenerate `src/generated/schema.ts` from the spec.               |
+| `npm run build`    | Clean, regenerate, then emit JS + declarations to `dist/`.        |
+| `npm run tsc`      | Regenerate, then type-check without emitting.                     |
+| `npm run clean`    | Remove the `dist/` directory.                                     |

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+import type { Client, ClientOptions } from 'openapi-fetch';
+import type { paths } from './generated/schema.js';
+/**
+ * A fully typed client for the Web Modeler (Hub) public API v2. Endpoints are
+ * called by path and method, e.g. `client.GET('/projects/{projectKey}', ...)`,
+ * with request and response types inferred from the OpenAPI spec.
+ */
+export type HubPublicApiClient = Client<paths>;
+/**
+ * A bearer token, or a (possibly async) function returning one. The function
+ * form is resolved on every request, so it can return a freshly refreshed
+ * token.
+ */
+export type BearerTokenProvider = string | (() => string | undefined | Promise<string | undefined>);
+export interface CreateHubPublicApiClientOptions extends ClientOptions {
+    /**
+     * Base URL of the API, including the `/api/v2` path segment, e.g.
+     * `https://modeler.camunda.io/api/v2`.
+     */
+    baseUrl: string;
+    /**
+     * Bearer token (JWT) used to authenticate requests. When provided, an
+     * `Authorization: Bearer <token>` header is attached to every request.
+     */
+    token?: BearerTokenProvider;
+}
+/**
+ * Creates a typed client for the Web Modeler (Hub) public API v2.
+ *
+ * @param options - Client configuration. `baseUrl` is required; `token`
+ *   enables bearer authentication. Any other `openapi-fetch` option (e.g. a
+ *   custom `fetch` or default `headers`) is forwarded.
+ * @returns A typed client exposing one method per HTTP verb.
+ */
+export declare function createHubPublicApiClient(options: CreateHubPublicApiClientOptions): HubPublicApiClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEpG,MAAM,WAAW,+BAAgC,SAAQ,aAAa;IACpE;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,+BAA+B,GAAG,kBAAkB,CAiBrG"}

package/dist/client.js

@@ -0,0 +1,33 @@
+/*
+ * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH under
+ * one or more contributor license agreements. See the NOTICE file distributed
+ * with this work for additional information regarding copyright ownership.
+ * Licensed under the Camunda License 1.0. You may not use this file
+ * except in compliance with the Camunda License 1.0.
+ */
+import createClient from 'openapi-fetch';
+/**
+ * Creates a typed client for the Web Modeler (Hub) public API v2.
+ *
+ * @param options - Client configuration. `baseUrl` is required; `token`
+ *   enables bearer authentication. Any other `openapi-fetch` option (e.g. a
+ *   custom `fetch` or default `headers`) is forwarded.
+ * @returns A typed client exposing one method per HTTP verb.
+ */
+export function createHubPublicApiClient(options) {
+    const { token, ...clientOptions } = options;
+    const client = createClient(clientOptions);
+    if (token !== undefined) {
+        client.use({
+            async onRequest({ request }) {
+                const value = typeof token === 'function' ? await token() : token;
+                if (value) {
+                    request.headers.set('Authorization', `Bearer ${value}`);
+                }
+                return request;
+            }
+        });
+    }
+    return client;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,YAAY,MAAM,eAAe,CAAC;AAgCzC;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAwC;IAC/E,MAAM,EAAE,KAAK,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC;IAC5C,MAAM,MAAM,GAAG,YAAY,CAAQ,aAAa,CAAC,CAAC;IAElD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC;YACT,KAAK,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE;gBACzB,MAAM,KAAK,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;gBAClE,IAAI,KAAK,EAAE,CAAC;oBACV,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,KAAK,EAAE,CAAC,CAAC;gBAC1D,CAAC;gBACD,OAAO,OAAO,CAAC;YACjB,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}