cantonjs-react 0.0.1 → 0.3.0

package/README.md

@@ -0,0 +1,213 @@
+# cantonjs-react
+
+React hooks for Canton Network dApps, powered by [TanStack Query](https://tanstack.com/query).
+
+[![npm version](https://img.shields.io/npm/v/cantonjs-react.svg)](https://www.npmjs.com/package/cantonjs-react)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/merged-one/cantonjs/blob/main/LICENSE)
+
+## Install
+
+```bash
+npm install cantonjs cantonjs-react @tanstack/react-query
+```
+
+## Quick Start
+
+```tsx
+import { CantonProvider, useContracts, useCreateContract } from 'cantonjs-react'
+import { createLedgerClient, jsonApi } from 'cantonjs'
+
+const client = createLedgerClient({
+  transport: jsonApi({ url: 'http://localhost:7575', token: jwt }),
+  actAs: 'Alice::1234',
+})
+
+function App() {
+  return (
+    <CantonProvider client={client}>
+      <AssetList />
+    </CantonProvider>
+  )
+}
+
+function AssetList() {
+  const { data: assets, isLoading } = useContracts({
+    templateId: '#my-pkg:Main:Asset',
+  })
+
+  const { mutate: create, isPending } = useCreateContract({
+    templateId: '#my-pkg:Main:Asset',
+  })
+
+  if (isLoading) return <div>Loading...</div>
+
+  return (
+    <div>
+      <button
+        disabled={isPending}
+        onClick={() => create({ createArguments: { owner: 'Alice', value: 100 } })}
+      >
+        Create Asset
+      </button>
+      <ul>
+        {assets?.map(c => (
+          <li key={c.createdEvent.contractId}>
+            {JSON.stringify(c.createdEvent.createArgument)}
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+## Public Scan Data Alongside Ledger Hooks
+
+`cantonjs-react` stays focused on participant-private ledger state. For public Splice data, use TanStack Query directly with `cantonjs-splice-scan`:
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+import { useContracts } from 'cantonjs-react'
+import { createScanClient } from 'cantonjs-splice-scan'
+
+const scan = createScanClient({
+  url: import.meta.env.VITE_SPLICE_SCAN_URL,
+})
+
+function NetworkDashboard() {
+  const { data: dso } = useQuery({
+    queryKey: ['scan', 'dso'],
+    queryFn: () => scan.getDsoInfo(),
+  })
+
+  const { data: assets } = useContracts({
+    templateId: '#my-pkg:Main:Asset',
+  })
+
+  return (
+    <div>
+      <pre>{JSON.stringify(dso, null, 2)}</pre>
+      <pre>{JSON.stringify(assets, null, 2)}</pre>
+    </div>
+  )
+}
+```
+
+This keeps public Scan reads and party-private ledger reads clearly separated. See [`../../docs/examples/react.md`](../../docs/examples/react.md) for the full example.
+
+## Hooks
+
+### `useContracts(options)`
+
+Query active contracts with automatic caching and deduplication.
+
+```tsx
+const { data, isLoading, error } = useContracts({
+  templateId: '#my-pkg:Main:Asset',
+  enabled: true,           // optional, default true
+  refetchInterval: 5000,   // optional, auto-refetch in ms
+})
+```
+
+### `useCreateContract(options)`
+
+Mutation hook for creating contracts. Automatically invalidates related queries on success.
+
+```tsx
+const { mutate: create, isPending, error } = useCreateContract({
+  templateId: '#my-pkg:Main:Asset',
+  onSuccess: (event) => console.log('Created:', event.contractId),
+})
+
+create({ createArguments: { owner: 'Alice', value: 100 } })
+```
+
+### `useExercise(options)`
+
+Mutation hook for exercising choices. Automatically invalidates related queries on success.
+
+```tsx
+const { mutate: exercise, isPending } = useExercise({
+  templateId: '#my-pkg:Main:Asset',
+  choice: 'Transfer',
+})
+
+exercise({
+  contractId: 'contract-id',
+  choiceArgument: { newOwner: 'Bob' },
+})
+```
+
+### `useStreamContracts(options)`
+
+Polling-based live contract updates (5-second interval).
+
+```tsx
+const { contracts, isLoading, error } = useStreamContracts({
+  templateId: '#my-pkg:Main:Asset',
+  enabled: true,  // optional
+})
+```
+
+### `useCantonClient()`
+
+Access the `LedgerClient` directly for advanced use cases.
+
+```tsx
+const client = useCantonClient()
+```
+
+### `useParty()`
+
+Get the current `actAs` party identity.
+
+```tsx
+const party = useParty()
+// 'Alice::1234'
+```
+
+## Provider
+
+Wrap your app with `CantonProvider`. Optionally pass a custom `QueryClient`:
+
+```tsx
+import { QueryClient } from '@tanstack/react-query'
+
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { staleTime: 10_000 } },
+})
+
+<CantonProvider client={ledgerClient} queryClient={queryClient}>
+  <App />
+</CantonProvider>
+```
+
+## Cache Invalidation
+
+Mutations automatically invalidate contract queries for the same template:
+
+- `useCreateContract` invalidates `['canton', 'contracts', templateId]`
+- `useExercise` invalidates `['canton', 'contracts', templateId]`
+
+This means `useContracts` queries refresh automatically after mutations complete.
+
+## Peer Dependencies
+
+| Package | Version |
+|---------|---------|
+| `react` | ^18.0.0 \|\| ^19.0.0 |
+| `@tanstack/react-query` | ^5.0.0 |
+
+## Requirements
+
+- Node.js >= 18
+- React 18 or 19
+
+## Related
+
+- [cantonjs](https://github.com/merged-one/cantonjs) &mdash; Core TypeScript library for Canton
+- [cantonjs-codegen](https://github.com/merged-one/cantonjs/tree/main/packages/cantonjs-codegen) &mdash; DAR-to-TypeScript code generation
+
+## License
+
+[Apache-2.0](https://github.com/merged-one/cantonjs/blob/main/LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cantonjs-react",
-  "version": "0.0.1",
+  "version": "0.3.0",
   "description": "React hooks for Canton Network dApps — built on cantonjs",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "node ../../scripts/verify-coverage-exclusions.mjs && vitest run --coverage",
     "lint": "eslint src",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run clean && npm run build"
@@ -35,7 +36,7 @@
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.0.0",
-    "cantonjs": "^0.0.1",
+    "cantonjs": "^0.3.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -48,6 +49,7 @@
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.0.0",
     "@types/react": "^18.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
     "jsdom": "^29.0.1",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",