@callimacus/thamyr-react 4.3.4

package/dist/types/query.d.ts

@@ -0,0 +1,110 @@
+/*!
+ * Copyright © 2025–2026 Solomei AI SRL. All rights reserved.
+ *
+ * Proprietary software, licensed for use by Callimacus customers only.
+ * See LICENSE.md for the full terms.
+ *
+ */
+import { UseMutationOptions, UseQueryOptions, DataTag } from '@tanstack/react-query';
+import { CallimacusApi } from '@callimacus/thamyr-core';
+
+/**
+TanStack Query bridge for the generated API surface.
+
+One generic adapter instead of per-endpoint factories: options are typed
+straight off the generated {@link CallimacusApi}, so every namespace and
+method — including ones added by future contract releases — is covered with
+zero per-operation code. The query function goes through {@link thamyrApi},
+so queries fired before `useInitThamyr()` completes wait for initialization
+instead of erroring.
+
+This bridge is hand-written only because hey-api's generated
+`@tanstack/react-query` factories do not compose with the SDK's
+`paramsStructure: 'flat'` (https://github.com/hey-api/hey-api/issues/3191).
+When that is fixed upstream, enable the plugin in openapi-ts.config.ts and
+replace this module's internals with re-exports of the generated factories —
+the `/query` subpath keeps consumers unchanged.
+
+Opt-in subpath: requires the `@tanstack/react-query` peer and a
+`QueryClientProvider`.
+
+@example
+```tsx
+import {useQuery, useMutation} from '@tanstack/react-query';
+import {thamyrQueryOptions, thamyrMutationOptions} from '@callimacus/thamyr-react/query';
+
+function HomePage({language}: {language: string}) {
+  // Refetches automatically when `language` changes (it is part of the key).
+  const {data, error} = useQuery(thamyrQueryOptions('content', 'getPage', {language, id: 'home'}));
+}
+
+function ShareButton({storyId}: {storyId: string}) {
+  const share = useMutation(thamyrMutationOptions('stories', 'share'));
+  return <button onClick={() => share.mutate({id: storyId})}>Share</button>;
+}
+```
+
+@packageDocumentation
+*/
+
+type AnyApiMethod = (parameters: never, options?: never) => Promise<{
+    data?: unknown;
+}>;
+/**
+A namespace of the generated client: `'content' | 'stories' | …`.
+*/
+type ApiNamespace = keyof CallimacusApi & string;
+/**
+The method names of one generated namespace.
+*/
+type ApiMethod<Namespace extends ApiNamespace> = {
+    [M in keyof CallimacusApi[Namespace] & string]: CallimacusApi[Namespace][M] extends AnyApiMethod ? M : never;
+}[keyof CallimacusApi[Namespace] & string];
+type MethodOf<Namespace extends ApiNamespace, Method extends ApiMethod<Namespace>> = Extract<CallimacusApi[Namespace][Method], AnyApiMethod>;
+/**
+The flat parameters object a generated method takes, or `void` for
+parameterless reads (e.g. `cart.getCart`), whose single slot is the
+request-options bag — offering that bag as "parameters" would put caller
+options into the query key and swallow the bridge's own request options.
+*/
+type ApiParameters<Namespace extends ApiNamespace, Method extends ApiMethod<Namespace>> = Parameters<MethodOf<Namespace, Method>> extends {
+    length: 0 | 1;
+} ? void : Parameters<MethodOf<Namespace, Method>>[0];
+/**
+The unwrapped success payload a generated method resolves.
+*/
+type ApiData<Namespace extends ApiNamespace, Method extends ApiMethod<Namespace>> = Awaited<ReturnType<MethodOf<Namespace, Method>>> extends {
+    data?: infer Data;
+} ? Exclude<Data, undefined> : never;
+/**
+The key of a bridge query: `['thamyr', namespace, method, parameters]`.
+*/
+type ThamyrQueryKey<Namespace extends ApiNamespace, Method extends ApiMethod<Namespace>> = readonly ['thamyr', Namespace, Method, ApiParameters<Namespace, Method>];
+type ThamyrQueryOptions<Namespace extends ApiNamespace, Method extends ApiMethod<Namespace>> = UseQueryOptions<ApiData<Namespace, Method>, Error, ApiData<Namespace, Method>, ThamyrQueryKey<Namespace, Method>> & {
+    queryKey: DataTag<ThamyrQueryKey<Namespace, Method>, ApiData<Namespace, Method>, Error>;
+};
+/**
+Query options for a generated read (`useQuery`, `prefetchQuery`,
+`ensureQueryData`, …). The key is `['thamyr', namespace, method, parameters]`,
+so parameter changes — a new language, a different id — refetch automatically.
+
+@example
+```tsx
+const {data: homePage} = useQuery(thamyrQueryOptions('content', 'getPage', {language, id: 'home'}));
+```
+*/
+declare function thamyrQueryOptions<const Namespace extends ApiNamespace, const Method extends ApiMethod<Namespace>>(namespace: Namespace, method: Method, parameters: ApiParameters<Namespace, Method>): ThamyrQueryOptions<Namespace, Method>;
+/**
+Mutation options for a generated write (`useMutation`). The mutation
+variables are the method's parameters object.
+
+@example
+```tsx
+const share = useMutation(thamyrMutationOptions('stories', 'share'));
+share.mutate({id: storyId});
+```
+*/
+declare function thamyrMutationOptions<const Namespace extends ApiNamespace, const Method extends ApiMethod<Namespace>>(namespace: Namespace, method: Method): UseMutationOptions<ApiData<Namespace, Method>, Error, ApiParameters<Namespace, Method>>;
+
+export { thamyrMutationOptions, thamyrQueryOptions };
+export type { ApiData, ApiMethod, ApiNamespace, ApiParameters, ThamyrQueryKey };

package/package.json

@@ -0,0 +1,69 @@
+{
+	"name": "@callimacus/thamyr-react",
+	"version": "4.3.4",
+	"private": false,
+	"description": "React package for Thamyr",
+	"license": "SEE LICENSE IN LICENSE.md",
+	"homepage": "https://docs.callimacus.ai/thamyr-sdk/react/1-overview",
+	"main": "dist/esm/index.js",
+	"module": "dist/esm/index.js",
+	"types": "dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/esm/index.js",
+			"types": "./dist/types/index.d.ts"
+		},
+		"./query": {
+			"import": "./dist/esm/query.js",
+			"types": "./dist/types/query.d.ts"
+		}
+	},
+	"files": [
+		"dist",
+		"CHANGELOG.md",
+		"CHANGELOG.core.md",
+		"MIGRATION.md"
+	],
+	"type": "module",
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org",
+		"@callimacus:registry": "https://registry.npmjs.org"
+	},
+	"scripts": {
+		"prepack": "cp ../../MIGRATION.md ./MIGRATION.md && cp ../core/CHANGELOG.md ./CHANGELOG.core.md",
+		"build": "rollup -c",
+		"dev": "rollup -c -w",
+		"clean": "rm -rf dist",
+		"test": "vitest run",
+		"lint": "eslint src"
+	},
+	"dependencies": {
+		"@callimacus/thamyr": "^4.3.4",
+		"@callimacus/thamyr-core": "^4.3.4",
+		"zustand": "^5.0.15"
+	},
+	"peerDependencies": {
+		"react": ">=18",
+		"@tanstack/react-query": "^5"
+	},
+	"devDependencies": {
+		"@eslint-react/eslint-plugin": "^5.20.8",
+		"@testing-library/react": "^16.3.3",
+		"@types/react": "^19.3.0",
+		"@types/react-dom": "^19.3.0",
+		"eslint-config-xo": "^4.0.1",
+		"eslint-plugin-react-hooks": "^7.1.1",
+		"jsdom": "^30.1.1",
+		"react": "^19.3.0",
+		"react-dom": "^19.3.0",
+		"vitest": "^5.0.2",
+		"@tanstack/react-query": "^5.104.0"
+	},
+	"gitHead": "fafba2c8ca0586f95b1d03c5eede356a53b00886",
+	"peerDependenciesMeta": {
+		"@tanstack/react-query": {
+			"optional": true
+		}
+	}
+}