@rytass/bpm-core-client 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -8,6 +8,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Releases are managed by [`nx release`](https://nx.dev/recipes/nx-release) with
 Conventional Commits — see `nx.json` for the release config.
 
+## 0.1.6 — 2026-05-28
+
+### Added
+
+- **`configureBPMClient({ baseUrl, authBaseUrl, fetch, headers })`**.
+  Server-side Node scripts (cron workers, org seeds, integration tests)
+  can now override the GraphQL endpoint, REST auth base URL, fetch
+  implementation, and default request headers programmatically without
+  relying on `NEXT_PUBLIC_API_URL` environment resolution. Both the
+  `requestGraphQl` GraphQL transport and the REST auth client honor the
+  override. Browser consumers under Next.js typically still rely on
+  `NEXT_PUBLIC_API_URL` and do not need to call this.
+
+  ```ts
+  import { configureBPMClient } from '@rytass/bpm-core-client';
+
+  configureBPMClient({
+    baseUrl: 'https://api.shuttle.example.com',
+    headers: { 'X-Service-Token': process.env.BPM_SYNC_TOKEN ?? '' },
+  });
+  ```
+
+### Documentation
+
+- README "Organization Mirror Pattern" rewritten with the correct
+  flat-input API shape (`updateOrgUnit({ id, code, name, type,
+  parentId, metadataJson })`, not the `{ id, input: {...} }` form the
+  0.1.5 example incorrectly showed). Adds a "Server-side base URL
+  override" section pointing at `configureBPMClient`.
+
+### Why a patch
+
+`configureBPMClient` is purely additive. Existing callers see no
+change to behavior unless they call the new API.
+
+## 0.1.5 — 2026-05-28
+
+### Documentation
+
+- **README "Organization mirror pattern" section.** Condensed pointer to
+  the full pattern in `@rytass/bpm-core-nestjs-module`'s README plus a
+  client-side worked example using `createOrgUnit`, `updateOrgUnit`,
+  `deleteOrgUnit`, `commitOrgUnitTreeDraft`, `createPosition`,
+  `createMembership`, `createManagerResolution`. Clarifies that BPM owns
+  the org graph and host applications mirror their existing org data in
+  rather than expose a resolver (in contrast to the member-resolver
+  pattern).
+
+### Why a patch
+
+No type or runtime change. README only.
+
+## 0.1.4 — 2026-05-27
+
+No source changes. Bumped in lockstep with
+`@rytass/bpm-core-nestjs-module@0.1.4` (re-publish after the 0.1.3
+backend tarball shipped only `.ts` source — see that package's CHANGELOG).
+
+## 0.1.3 — 2026-05-27 (deprecated on npm)
+
+Lockstep bump alongside the broken 0.1.3 backend release. Avoid;
+upgrade directly to 0.1.4 or newer.
+
 ## 0.1.2 — 2026-05-27
 
 No source changes. Bumped in lockstep with

package/README.md

@@ -151,9 +151,9 @@ default endpoint, no cookie jar. Treat them the same as Server Components.
 
 ## Endpoint Resolution
 
-By default the client targets the same origin (no `/api` prefix) — see
-[`docs/10-bpm-embedding-auth.md`](../../docs/10-bpm-embedding-auth.md) for the
-host contract. Endpoint resolution rules:
+By default the client targets the same origin (no `/api` prefix) — see the
+"Embedding & auth" section of `@rytass/bpm-core-nestjs-module`'s README for
+the host-side contract. Endpoint resolution rules:
 
 | Source                                          | Behavior                                                                   |
 | ----------------------------------------------- | -------------------------------------------------------------------------- |
@@ -206,6 +206,108 @@ Every subpath uses the same `requestGraphQl` transport from the root. Hosts
 can mix and match — for example a read-only dashboard might only import
 `workflow` queries, never reaching for `/organization` mutations.
 
+## Organization Mirror Pattern (Important)
+
+> **TL;DR:** BPM owns the org graph (`org_units`, `positions`,
+> `memberships`, `manager_resolutions`). Hosts with their own org model
+> mirror data **into** BPM via the `/organization` mutations rather than
+> exposing a host-side resolver. See the
+> "Organization Data Ownership" section of
+> `@rytass/bpm-core-nestjs-module`'s README for the rationale.
+
+The integration shape is **asymmetric** with `BPMMemberResolver`:
+member identity stays in the host's user table and BPM reaches in via
+the resolver token; the org structure lives in BPM and the host pushes
+data in. Three rules keep the mirror idempotent:
+
+1. **Use `code` as the natural key.** Both `OrgUnit` and `Position`
+   carry a unique `code` you control. On every sync, look up by `code`
+   before deciding INSERT vs UPDATE.
+2. **Stash the host-FK in `metadata`.** Both entities carry an opaque
+   `metadata` JSON BPM never introspects — store your host's primary
+   key there to chase pointers back during reconciliation.
+3. **Soft-delete via the `delete*` mutations.** They set `deletedAt`;
+   live queries (`orgUnits`, `orgUnitCount`, etc.) filter soft-deleted
+   rows automatically.
+
+Quick wire-up using only this package's exports. Note the flat input
+shape on the create/update mutations (no `{id, input: {...}}` wrapper):
+
+```ts
+import {
+  readOrganizationDashboard,
+  createOrgUnit,
+  updateOrgUnit,
+} from '@rytass/bpm-core-client/organization';
+import type { OrgUnitType } from '@rytass/bpm-core-shared';
+
+async function upsertOrgUnit(hostUnit: {
+  code: string;
+  name: string;
+  type: OrgUnitType;
+  parentCode: string | null;
+  hostId: string;
+}): Promise<string> {
+  // One round trip pulls every org unit; index by code in your sync loop.
+  const dash = await readOrganizationDashboard({ orgUnitPageSize: null });
+  const existing = dash.orgUnits.find((u) => u.code === hostUnit.code);
+  const parentId = hostUnit.parentCode
+    ? dash.orgUnits.find((u) => u.code === hostUnit.parentCode)?.id ?? null
+    : null;
+  const metadataJson = JSON.stringify({ hostId: hostUnit.hostId });
+
+  if (existing) {
+    return (
+      await updateOrgUnit({
+        id: existing.id,
+        code: hostUnit.code,
+        name: hostUnit.name,
+        type: hostUnit.type,
+        parentId,
+        metadataJson,
+      })
+    ).id;
+  }
+  return (
+    await createOrgUnit({
+      code: hostUnit.code,
+      name: hostUnit.name,
+      type: hostUnit.type,
+      parentId,
+      metadataJson,
+    })
+  ).id;
+}
+```
+
+`createPosition`, `createMembership`, `updateMembership`, and
+`createManagerResolution` follow the same flat-input pattern. For bulk
+tree moves in one transaction, see `commitOrgUnitTreeDraft`. **Only**
+that one mutation is transactional — sequential `createMembership` calls
+are independent and partial-failures stay committed.
+
+### Server-side base URL override
+
+The GraphQL client resolves its endpoint via `NEXT_PUBLIC_API_URL` or
+same-origin. Node scripts that aren't running inside Next.js (cron
+workers, one-off org seeds, integration tests) should call
+`configureBPMClient` from the root package barrel once at startup:
+
+```ts
+import { configureBPMClient } from '@rytass/bpm-core-client';
+
+configureBPMClient({
+  baseUrl: 'https://api.shuttle.example.com',
+  // Optional: inject your own fetch (e.g. node-fetch) or default headers.
+  fetch: globalThis.fetch,
+  headers: { 'X-Service-Token': process.env.BPM_SYNC_TOKEN ?? '' },
+});
+```
+
+All subsequent calls to `requestGraphQl` and the REST auth client honor
+the override. Both `baseUrl` and `headers` are static for the process
+lifetime — call `configureBPMClient` again to replace.
+
 ## Auth REST Endpoints
 
 The BPM wrapper-host exposes the following endpoints under the host root (no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-client",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Framework-agnostic TypeScript client for the Rytass BPM approval workflow GraphQL surface: fetch-based GraphQL transport, REST auth client, pre-baked typed operations for organization, member, form, template, and workflow.",
   "keywords": [
     "bpm",
@@ -73,7 +73,7 @@
     }
   },
   "peerDependencies": {
-    "@rytass/bpm-core-shared": "^0.1.4"
+    "@rytass/bpm-core-shared": "^0.1.6"
   },
   "dependencies": {
     "tslib": "^2.3.0"

package/src/index.d.ts

@@ -1,3 +1,4 @@
 export * from './lib/api-auth-client';
+export * from './lib/client-config';
 export * from './lib/graphql-client';
 export * from './lib/member-api';

package/src/index.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./lib/api-auth-client"), exports);
+tslib_1.__exportStar(require("./lib/client-config"), exports);
 tslib_1.__exportStar(require("./lib/graphql-client"), exports);
 tslib_1.__exportStar(require("./lib/member-api"), exports);
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/bpm-core-client/src/index.ts"],"names":[],"mappings":";;;AAAA,gEAAsC;AACtC,+DAAqC;AACrC,2DAAiC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/bpm-core-client/src/index.ts"],"names":[],"mappings":";;;AAAA,gEAAsC;AACtC,8DAAoC;AACpC,+DAAqC;AACrC,2DAAiC"}

package/src/lib/api-auth-client.js

@@ -7,6 +7,7 @@ exports.readApiCurrentMember = readApiCurrentMember;
 exports.readApiBaseUrl = readApiBaseUrl;
 exports.resolveApiBaseUrlFromGraphQlEndpoint = resolveApiBaseUrlFromGraphQlEndpoint;
 const graphql_client_1 = require("./graphql-client");
+const client_config_1 = require("./client-config");
 /**
  * Lists seeded test members exposed by the host's `/auth/test-members`
  * endpoint. Hosts targeting production typically disable this endpoint or
@@ -71,6 +72,10 @@ async function readApiCurrentMember() {
  *    assumed to expose both `/graphql` and `/auth/*` at the same origin.
  */
 function readApiBaseUrl() {
+    const config = (0, client_config_1.readBPMClientConfig)();
+    if (config.authBaseUrl?.trim()) {
+        return config.authBaseUrl.trim().replace(/\/$/, '');
+    }
     const explicitApiBaseUrl = process.env.NEXT_PUBLIC_API_AUTH_URL?.trim();
     if (explicitApiBaseUrl) {
         return explicitApiBaseUrl.replace(/\/$/, '');
@@ -89,9 +94,12 @@ function resolveApiBaseUrlFromGraphQlEndpoint(graphQlEndpoint) {
     return endpoint.toString().replace(/\/$/, '');
 }
 async function requestApi(path, init) {
-    const response = await fetch(`${readApiBaseUrl()}${path}`, {
+    const fetchImpl = (0, client_config_1.resolveBPMFetch)();
+    const configuredHeaders = (0, client_config_1.readBPMConfiguredHeaders)();
+    const response = await fetchImpl(`${readApiBaseUrl()}${path}`, {
         credentials: 'include',
         ...init,
+        headers: { ...configuredHeaders, ...(init?.headers ?? {}) },
     });
     if (!response.ok) {
         throw new ApiRequestError(response.status, await readError(response));

package/src/lib/api-auth-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-auth-client.js","sourceRoot":"","sources":["../../../../../libs/bpm-core-client/src/lib/api-auth-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-auth-client.js","sourceRoot":"","sources":["../../../../../libs/bpm-core-client/src/lib/api-auth-client.ts"],"names":[],"mappings":"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"}

package/src/lib/client-config.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Programmatic configuration override for the BPM client transport.
+ *
+ * The default endpoint resolution (`NEXT_PUBLIC_API_URL` → localhost →
+ * same-origin) covers Next.js consumers. Node-side scripts (cron
+ * workers, one-off org seeds, integration tests) usually cannot rely on
+ * environment variables and need a programmatic hook. Call
+ * {@link configureBPMClient} once at startup; subsequent
+ * `requestGraphQl` and REST auth calls honor the override.
+ */
+export interface BPMClientConfig {
+    /**
+     * Override the GraphQL endpoint URL. When provided, takes precedence
+     * over `NEXT_PUBLIC_API_URL` and the default localhost / same-origin
+     * resolution. Pass an absolute URL ending without `/graphql` to also
+     * derive the REST `/auth/*` base URL automatically, or pass the full
+     * `https://host/graphql` form to set the GraphQL endpoint directly.
+     *
+     * If you need different bases for GraphQL vs `/auth/*` (rare — most
+     * hosts colocate them), set both `baseUrl` and `authBaseUrl`.
+     */
+    readonly baseUrl?: string;
+    /**
+     * Override the REST `/auth/*` base URL independently of `baseUrl`.
+     * Most hosts colocate GraphQL and auth on the same origin; this knob
+     * exists for the rare split-origin deployment.
+     */
+    readonly authBaseUrl?: string;
+    /**
+     * Replace the global `fetch` implementation. Useful when running on a
+     * runtime without a global `fetch` (older Node versions, edge runtimes
+     * with custom polyfills) or when you want to inject a tracing wrapper.
+     */
+    readonly fetch?: typeof fetch;
+    /**
+     * Additional headers merged into every outbound request. Use this to
+     * pass service tokens, tracing headers, or a server-side session
+     * cookie that the browser would normally send automatically.
+     *
+     * Note: `Content-Type` is set internally for GraphQL POSTs and
+     * cannot be overridden through this option.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * Sets the active {@link BPMClientConfig}. Subsequent calls **replace**
+ * the previous configuration; pass `{}` to reset to environment-based
+ * defaults.
+ *
+ * Idiomatic call site is the very top of a Node worker's bootstrap:
+ *
+ * ```ts
+ * import { configureBPMClient } from '@rytass/bpm-core-client';
+ *
+ * configureBPMClient({
+ *   baseUrl: 'https://api.shuttle.example.com',
+ *   headers: { 'X-Service-Token': process.env.BPM_SYNC_TOKEN ?? '' },
+ * });
+ * ```
+ *
+ * Browser consumers under Next.js typically do **not** need to call
+ * this — `NEXT_PUBLIC_API_URL` plus same-origin defaults cover the
+ * common case.
+ */
+export declare function configureBPMClient(config: BPMClientConfig): void;
+/**
+ * Reads the active {@link BPMClientConfig}. Exposed primarily for tests
+ * and for inspecting the current override at runtime — consumers should
+ * use {@link configureBPMClient} to mutate, never reach in directly.
+ */
+export declare function readBPMClientConfig(): BPMClientConfig;
+/**
+ * Resolves the effective `fetch` implementation honoring the active
+ * override, falling back to the global `fetch`.
+ */
+export declare function resolveBPMFetch(): typeof fetch;
+/**
+ * Returns the headers configured via {@link configureBPMClient}.
+ * Internal transports merge these into every outbound request.
+ */
+export declare function readBPMConfiguredHeaders(): Readonly<Record<string, string>>;

package/src/lib/client-config.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Programmatic configuration override for the BPM client transport.
+ *
+ * The default endpoint resolution (`NEXT_PUBLIC_API_URL` → localhost →
+ * same-origin) covers Next.js consumers. Node-side scripts (cron
+ * workers, one-off org seeds, integration tests) usually cannot rely on
+ * environment variables and need a programmatic hook. Call
+ * {@link configureBPMClient} once at startup; subsequent
+ * `requestGraphQl` and REST auth calls honor the override.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureBPMClient = configureBPMClient;
+exports.readBPMClientConfig = readBPMClientConfig;
+exports.resolveBPMFetch = resolveBPMFetch;
+exports.readBPMConfiguredHeaders = readBPMConfiguredHeaders;
+let currentConfig = {};
+/**
+ * Sets the active {@link BPMClientConfig}. Subsequent calls **replace**
+ * the previous configuration; pass `{}` to reset to environment-based
+ * defaults.
+ *
+ * Idiomatic call site is the very top of a Node worker's bootstrap:
+ *
+ * ```ts
+ * import { configureBPMClient } from '@rytass/bpm-core-client';
+ *
+ * configureBPMClient({
+ *   baseUrl: 'https://api.shuttle.example.com',
+ *   headers: { 'X-Service-Token': process.env.BPM_SYNC_TOKEN ?? '' },
+ * });
+ * ```
+ *
+ * Browser consumers under Next.js typically do **not** need to call
+ * this — `NEXT_PUBLIC_API_URL` plus same-origin defaults cover the
+ * common case.
+ */
+function configureBPMClient(config) {
+    currentConfig = { ...config };
+}
+/**
+ * Reads the active {@link BPMClientConfig}. Exposed primarily for tests
+ * and for inspecting the current override at runtime — consumers should
+ * use {@link configureBPMClient} to mutate, never reach in directly.
+ */
+function readBPMClientConfig() {
+    return currentConfig;
+}
+/**
+ * Resolves the effective `fetch` implementation honoring the active
+ * override, falling back to the global `fetch`.
+ */
+function resolveBPMFetch() {
+    return currentConfig.fetch ?? globalThis.fetch;
+}
+/**
+ * Returns the headers configured via {@link configureBPMClient}.
+ * Internal transports merge these into every outbound request.
+ */
+function readBPMConfiguredHeaders() {
+    return currentConfig.headers ?? {};
+}
+//# sourceMappingURL=client-config.js.map

package/src/lib/client-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-config.js","sourceRoot":"","sources":["../../../../../libs/bpm-core-client/src/lib/client-config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AA8DH,gDAEC;AAOD,kDAEC;AAMD,0CAEC;AAMD,4DAEC;AAjDD,IAAI,aAAa,GAAoB,EAAE,CAAC;AAExC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,kBAAkB,CAAC,MAAuB;IACxD,aAAa,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB;IACjC,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe;IAC7B,OAAO,aAAa,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB;IACtC,OAAO,aAAa,CAAC,OAAO,IAAI,EAAE,CAAC;AACrC,CAAC"}

package/src/lib/graphql-client.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.requestGraphQl = requestGraphQl;
 exports.readGraphQlEndpoint = readGraphQlEndpoint;
 exports.resolveDefaultGraphQlEndpoint = resolveDefaultGraphQlEndpoint;
+const client_config_1 = require("./client-config");
 const LOCAL_GRAPHQL_ENDPOINT = 'http://localhost:17603/graphql';
 const SAME_ORIGIN_GRAPHQL_ENDPOINT = '/graphql';
 /**
@@ -32,7 +33,8 @@ const SAME_ORIGIN_GRAPHQL_ENDPOINT = '/graphql';
  * ```
  */
 async function requestGraphQl(query, variables) {
-    const response = await fetch(readGraphQlEndpoint(), {
+    const fetchImpl = (0, client_config_1.resolveBPMFetch)();
+    const response = await fetchImpl(readGraphQlEndpoint(), {
         body: JSON.stringify({ query, variables }),
         credentials: 'include',
         headers: buildGraphQlHeaders(),
@@ -61,6 +63,12 @@ async function requestGraphQl(query, variables) {
  *    runtimes such as Node SSR).
  */
 function readGraphQlEndpoint() {
+    const configured = (0, client_config_1.readBPMClientConfig)().baseUrl?.trim();
+    if (configured) {
+        return configured.endsWith('/graphql')
+            ? configured
+            : `${configured.replace(/\/$/, '')}/graphql`;
+    }
     return (readOptionalPublicEnvValue(process.env.NEXT_PUBLIC_API_URL) ??
         resolveDefaultGraphQlEndpoint(readBrowserHostname()));
 }
@@ -77,6 +85,7 @@ function resolveDefaultGraphQlEndpoint(hostname) {
 }
 function buildGraphQlHeaders() {
     return {
+        ...(0, client_config_1.readBPMConfiguredHeaders)(),
         'Content-Type': 'application/json',
     };
 }

package/src/lib/graphql-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"graphql-client.js","sourceRoot":"","sources":["../../../../../libs/bpm-core-client/src/lib/graphql-client.ts"],"names":[],"mappings":";;AAsCA,wCA0BC;AAYD,kDAKC;AAQD,sEAMC;AA/FD,MAAM,sBAAsB,GAAG,gCAAgC,CAAC;AAChE,MAAM,4BAA4B,GAAG,UAAU,CAAC;AAWhD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACI,KAAK,UAAU,cAAc,CAClC,KAAa,EACb,SAA6C;IAE7C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,mBAAmB,EAAE,EAAE;QAClD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAC1C,WAAW,EAAE,SAAS;QACtB,OAAO,EAAE,mBAAmB,EAAE;QAC9B,MAAM,EAAE,MAAM;KACf,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA2B,CAAC;IAElE,IAAI,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,OAAO,CAAC,IAAI,CAAC;AACtB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,mBAAmB;IACjC,OAAO,CACL,0BAA0B,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;QAC3D,6BAA6B,CAAC,mBAAmB,EAAE,CAAC,CACrD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,6BAA6B,CAC3C,QAAuB;IAEvB,OAAO,WAAW,CAAC,QAAQ,CAAC;QAC1B,CAAC,CAAC,sBAAsB;QACxB,CAAC,CAAC,4BAA4B,CAAC;AACnC,CAAC;AAED,SAAS,mBAAmB;IAC1B,OAAO;QACL,cAAc,EAAE,kBAAkB;KACnC,CAAC;AACJ,CAAC;AAED,SAAS,0BAA0B,CAAC,KAAyB;IAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;AAC/B,CAAC;AAED,SAAS,mBAAmB;IAC1B,OAAO,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;AACzE,CAAC;AAED,SAAS,WAAW,CAAC,QAAuB;IAC1C,OAAO,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,WAAW,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"graphql-client.js","sourceRoot":"","sources":["../../../../../libs/bpm-core-client/src/lib/graphql-client.ts"],"names":[],"mappings":";;AA4CA,wCA2BC;AAYD,kDAWC;AAQD,sEAMC;AA5GD,mDAIyB;AAEzB,MAAM,sBAAsB,GAAG,gCAAgC,CAAC;AAChE,MAAM,4BAA4B,GAAG,UAAU,CAAC;AAWhD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACI,KAAK,UAAU,cAAc,CAClC,KAAa,EACb,SAA6C;IAE7C,MAAM,SAAS,GAAG,IAAA,+BAAe,GAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,mBAAmB,EAAE,EAAE;QACtD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAC1C,WAAW,EAAE,SAAS;QACtB,OAAO,EAAE,mBAAmB,EAAE;QAC9B,MAAM,EAAE,MAAM;KACf,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA2B,CAAC;IAElE,IAAI,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,OAAO,CAAC,IAAI,CAAC;AACtB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,mBAAmB;IACjC,MAAM,UAAU,GAAG,IAAA,mCAAmB,GAAE,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;IACzD,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC;YACpC,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC;IACjD,CAAC;IACD,OAAO,CACL,0BAA0B,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;QAC3D,6BAA6B,CAAC,mBAAmB,EAAE,CAAC,CACrD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,6BAA6B,CAC3C,QAAuB;IAEvB,OAAO,WAAW,CAAC,QAAQ,CAAC;QAC1B,CAAC,CAAC,sBAAsB;QACxB,CAAC,CAAC,4BAA4B,CAAC;AACnC,CAAC;AAED,SAAS,mBAAmB;IAC1B,OAAO;QACL,GAAG,IAAA,wCAAwB,GAAE;QAC7B,cAAc,EAAE,kBAAkB;KACnC,CAAC;AACJ,CAAC;AAED,SAAS,0BAA0B,CAAC,KAAyB;IAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;AAC/B,CAAC;AAED,SAAS,mBAAmB;IAC1B,OAAO,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;AACzE,CAAC;AAED,SAAS,WAAW,CAAC,QAAuB;IAC1C,OAAO,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,WAAW,CAAC;AAC9D,CAAC"}