@welshare/react 0.0.1-alpha.1

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2025 Welshare Health UG (haftungsbeschränkt) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @welshare/react
+
+### Disclaimer, notes on maturity
+
+This library is in Alpha / demo state at this moment. We're using it to review the security aspects while data is in transfer and in rest. There's absolutely no guarantee or warrant that at this point any data is safe. All data can be lost at any time - even though we're using resources that puts decentralization and resilience values to the front. Be **very** careful if you're integrating this into user facing code. Welshare Health wallets are controlled by cryptographic material which _can_ be stored in non custodial / MPC environments (Privy). While that's considered very safe, we can't guarantee at this point that we've already got each aspect of inter application communication or key derivation features right, so don't connect wallets that store significant value with the welshare wallet yet.
+
+## Purpose
+
+This is a React library that helps integrating with Welshare's sovereign data sharing platform. This package provides React hooks and components to connect applications with Welshare's wallet for secure data submission.
+
+## Installation
+
+```bash
+npm install @welshare/react
+# or
+yarn add @welshare/react
+# or
+pnpm add @welshare/react
+```
+
+## Peer Dependencies
+
+This package requires React 19+ as a peer dependency.
+
+## Prerequisites
+
+You need to register an app identifier using the Welshare Wallet frontend first: https://wallet.welshare.app/application. We're referring to this as `your-application-id` from here on.
+
+If you want to submit questionnaire data, your application must first register a new questionnaire definition. You can also reuse an existing questionnaire id to let users contribute responses to another app's questionaire, but that's not highly encouraged at this point.
+
+## Data Submissions
+
+At the moment there are only two supported submission types: Fhir compatible QuestionnaireResponses and our custom "Reflex" app submissions. Both types are identified by schema uids that are accessible on the `Schemas` export.
+
+```
+export const Schemas = {
+  QuestionnaireResponse: "b14b538f-7de3-4767-ad77-464d755d78bd"
+};
+```
+
+To submit questionnaires using custom frontends, you'll use the `useWelshare` hook to open a wallet dialog that lets your application talk to the user's connected wallets (using derived storage keys). All communication with the Welshare infrastructure happens inside that browser window.
+
+## Code Sample
+
+```tsx
+import { ConnectWelshareButton, Schemas, useWelshare } from "@welshare/react";
+
+export function QuestionnaireForm() {
+  const { isConnected, openWallet, submitData } = useWelshare({
+    applicationId: <your-application-id>,
+    environment: "development", //optional, at the moment the environment is always development
+    callbacks: {
+      onUploaded: (payload) => console.log('Data uploaded:', payload),
+      onError: (error) => console.error('Error:', error),
+      onSessionReady: (storageKey) => console.log('Session ready:', storageKey),
+    }
+  });
+
+  const handleSubmit = () => {
+    //response is a QuestionnaireResponse compatible object
+    submitData(Schemas.QuestionnaireResponse, response);
+  };
+
+  // using the `ConnectWelshareButton` is not mandatory. Use your own buttons if you feel like it.
+  return (
+    <div>
+      {!isConnected ? (
+        <ConnectWelshareButton openWallet={openWallet}>
+          Connect to Welshare
+        </ConnectWelshareButton>
+      ) : (
+        <form>
+          {/* ... some form that collects your response data ... */}
+          <button onClick={() => handleSubmit(response)} disabled={isSubmitting}>
+            {isSubmitting ? 'Submitting...' : 'Submit Data'}
+          </button>
+        </form>
+      )}
+    </div>
+  );
+}
+```
+
+## API
+
+### supported callbacks
+
+those are configured in the `useWelshare` options parameter and called back during interactions with the wallet dialog
+
+```tsx
+  callbacks: {
+    onUploaded?: (payload: SubmissionPayload<unknown>) => void;
+    onError?: (error: string) => void;
+    onSessionReady?: (sessionPubKey: string) => void;
+    onDialogClosing?: () => void;
+    onDialogReady?: () => void;
+  }
+```
+
+## Security Notes
+
+No part of this application deals with a "blockchain" directly (Nillion nodes are validated by a custom chain but that's not a fact relevant for end users' security in this scope).
+
+The EVM addresses that control a user profile are (supposedly) never leaked to a third party.
+
+The key derivation mechanism that creates new storage keys that users use to sign messages is not guaranteed to be 100% sound. At this moment it's used as a cryptographic authenticator, but the derivation mechanism will change in the future, rendering already existing keys obsolete. We're not guaranteeing that your key material stays trivially derivable.
+
+Data is stored on [nilDB (by Nillion)](https://docs.nillion.com/build/private-storage/quickstart), a system that can enforces access control, encryption at rest and storage redundancy. While technically possible, the current library does not MPC-encrypt any information. The data is sent to nilDB by a _user client_ that's controlled by the user's own key material. Welshare only delegates NUCs (access rights) to the users. Right now the welshare builder _can_ read any data users upload. This concept will eventually change - welshare's goal is to only make user originated information available inside trusted execution environments.
+
+## Development
+
+This package is built using:
+
+- TypeScript
+- Tshy for build management
+- Vitest for testing
+
+## License
+
+MIT. See the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+Get in touch on Telegram. Check https://welshare.health

package/dist/esm/components/connect-button.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+export declare const ConnectWelshareButton: (props: {
+    openWallet: () => void;
+    children?: React.ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=connect-button.d.ts.map

package/dist/esm/components/connect-button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-button.d.ts","sourceRoot":"","sources":["../../../src/components/connect-button.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,eAAO,MAAM,qBAAqB,UAAW;IAC3C,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,4CAgFA,CAAC"}

package/dist/esm/components/connect-button.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export const ConnectWelshareButton = (props) => {
+    // Self-contained styles that won't conflict with external applications
+    const buttonStyles = {
+        // Reset any inherited styles
+        all: 'unset',
+        boxSizing: 'border-box',
+        // Layout
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: '100%',
+        minHeight: '44px',
+        padding: '12px 24px',
+        // Typography
+        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+        fontSize: '16px',
+        fontWeight: '600',
+        lineHeight: '1.5',
+        textAlign: 'center',
+        textDecoration: 'none',
+        whiteSpace: 'nowrap',
+        // Visual styling
+        backgroundColor: '#0198ff',
+        background: 'linear-gradient(135deg, #0198ff 0%, #16ffef 100%)',
+        color: '#ffffff',
+        border: 'none',
+        borderRadius: '8px',
+        cursor: 'pointer',
+        transition: 'all 0.2s ease-in-out',
+        // Accessibility
+        userSelect: 'none',
+        WebkitUserSelect: 'none',
+        MozUserSelect: 'none',
+        // Focus states
+        outline: 'none',
+    };
+    // Handle hover and focus states since inline styles don't support pseudo-selectors
+    const handleMouseEnter = (e) => {
+        e.currentTarget.style.transform = 'translateY(-1px)';
+        e.currentTarget.style.boxShadow = '0 4px 12px rgba(1, 152, 255, 0.3)';
+    };
+    const handleMouseLeave = (e) => {
+        e.currentTarget.style.transform = 'translateY(0)';
+        e.currentTarget.style.boxShadow = '0 2px 6px rgba(1, 152, 255, 0.2)';
+    };
+    const handleMouseDown = (e) => {
+        e.currentTarget.style.transform = 'translateY(0)';
+        e.currentTarget.style.boxShadow = '0 2px 6px rgba(1, 152, 255, 0.2)';
+    };
+    const handleFocus = (e) => {
+        e.currentTarget.style.boxShadow = '0 0 0 3px rgba(1, 152, 255, 0.3)';
+    };
+    const handleBlur = (e) => {
+        e.currentTarget.style.boxShadow = '0 2px 6px rgba(1, 152, 255, 0.2)';
+    };
+    return (_jsx("button", { onClick: props.openWallet, style: buttonStyles, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, onMouseDown: handleMouseDown, onFocus: handleFocus, onBlur: handleBlur, type: "button", children: props.children || "Connect Welshare Profile" }));
+};

package/dist/esm/hooks/use-welshare.d.ts

@@ -0,0 +1,10 @@
+import { SubmissionPayload, SubmissionSchemaId, WelshareConnectionOptions } from "@/types.js";
+export declare const useWelshare: (props: WelshareConnectionOptions) => {
+    isConnected: boolean;
+    storageKey: string | undefined;
+    openWallet: () => void;
+    isDialogOpen: boolean;
+    submitData: <T>(schemaId: SubmissionSchemaId, submission: SubmissionPayload<T>) => void;
+    isSubmitting: boolean;
+};
+//# sourceMappingURL=use-welshare.d.ts.map

package/dist/esm/hooks/use-welshare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-welshare.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-welshare.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,WAAW,UAAW,yBAAyB;;;;;iBAkFtC,CAAC,YACT,kBAAkB,cAChB,iBAAiB,CAAC,CAAC,CAAC;;CAuDnC,CAAC"}

package/dist/esm/hooks/use-welshare.js

@@ -0,0 +1,111 @@
+import { useEffect, useState } from "react";
+export const useWelshare = (props) => {
+    const [storageKey, setStorageKey] = useState();
+    const [isDialogOpen, setIsDialogOpen] = useState(false);
+    const [dialogWindow, setDialogWindow] = useState(null);
+    const [messageIdCounter, setMessageIdCounter] = useState(0);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const options = {
+        environment: "development",
+        apiBaseUrl: "https://wallet.welshare.health",
+        ...props,
+    };
+    const WELSHARE_WALLET_URL = `${options.apiBaseUrl}/wallet-external`;
+    useEffect(() => {
+        const handleMessage = (event) => {
+            // Verify origin for security
+            if (event.origin !== new URL(WELSHARE_WALLET_URL).origin) {
+                return;
+            }
+            const message = event.data;
+            let errorMessage = "";
+            switch (message.type) {
+                case "ERROR":
+                    errorMessage = message.payload.error || "An unknown error occurred";
+                    console.error("Welshare Wallet sent an error:", errorMessage);
+                    setIsSubmitting(false);
+                    options.callbacks.onError?.(errorMessage);
+                    break;
+                case "DIALOG_READY":
+                    setIsDialogOpen(true);
+                    console.debug("Welshare Wallet Dialog is ready");
+                    break;
+                case "SESSION_READY":
+                    if (!message.payload.sessionPublicKey) {
+                        errorMessage = "No session public key found";
+                        console.error("Welshare Wallet sent a session without a key:", message.payload);
+                        setStorageKey(undefined);
+                        options.callbacks.onError?.(errorMessage);
+                        break;
+                    }
+                    console.debug("Welshare Profile Session ready", message.payload);
+                    setStorageKey(message.payload.sessionPublicKey);
+                    options.callbacks.onSessionReady?.(message.payload.sessionPublicKey);
+                    break;
+                case "DIALOG_CLOSING":
+                    console.debug("Welshare Wallet Dialog is closing");
+                    setStorageKey(undefined);
+                    setIsDialogOpen(false);
+                    options.callbacks.onDialogClosing?.();
+                    break;
+                case "DATA_UPLOADED":
+                    console.debug("data uploaded", message.payload);
+                    setIsSubmitting(false);
+                    options.callbacks.onUploaded?.(message.payload);
+                    break;
+                default:
+                    console.log("Received unexpected message from Welshare Wallet:", message);
+            }
+        };
+        window.addEventListener("message", handleMessage);
+        return () => {
+            window.removeEventListener("message", handleMessage);
+        };
+    }, [WELSHARE_WALLET_URL, options.callbacks]);
+    /**
+     * @param schemaType a welshare schema type uid
+     * @param submission your submission that validates against the schema type
+     */
+    const submitData = (schemaId, submission) => {
+        if (!dialogWindow) {
+            throw new Error("Dialog window not open");
+        }
+        const submissionPayload = {
+            applicationId: options.applicationId,
+            schemaId,
+            timestamp: new Date(),
+            submission,
+        };
+        //todo: before submitting data, consider verifying it locally here;
+        // 1. request the actual schema using a welshare api
+        // 2. create a json schema validator
+        // 3. run payload against that validator
+        // 4. submit
+        const message = {
+            type: "SUBMIT_DATA",
+            payload: submissionPayload,
+            id: String(messageIdCounter),
+        };
+        dialogWindow.postMessage(message, WELSHARE_WALLET_URL);
+        setIsSubmitting(true);
+        setMessageIdCounter((prev) => prev + 1);
+    };
+    const openWallet = () => {
+        const width = 800;
+        const height = 600;
+        const left = window.screenX + (window.outerWidth - width) / 2;
+        const top = window.screenY + (window.outerHeight - height) / 2;
+        const newWindow = window.open(WELSHARE_WALLET_URL, "Welshare Wallet", `width=${width},height=${height},left=${left},top=${top}`);
+        if (newWindow) {
+            setDialogWindow(newWindow);
+        }
+    };
+    return {
+        isConnected: !!storageKey,
+        storageKey,
+        openWallet,
+        isDialogOpen,
+        submitData,
+        isSubmitting,
+    };
+};

package/dist/esm/index.d.ts

@@ -0,0 +1,7 @@
+export { ConnectWelshareButton } from "./components/connect-button.js";
+export { useWelshare } from "./hooks/use-welshare.js";
+export declare const Schemas: {
+    QuestionnaireResponse: string;
+    ReflexSubmission: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAEvE,OAAO,EACL,WAAW,EACZ,MAAM,yBAAyB,CAAC;AAGjC,eAAO,MAAM,OAAO;;;CAGnB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,10 @@
+//todo: this is not tree shaken and leaks nillion dependencies transitively. Consider pulling it up
+//import { QuestionnaireResponseSchema, ReflexSubmissionSchema } from "@welshare/sdk";
+export { ConnectWelshareButton } from "./components/connect-button.js";
+// ---- hooks ----
+export { useWelshare } from "./hooks/use-welshare.js";
+//todo: import them from the SDK or a dedicated SDK constants export
+export const Schemas = {
+    QuestionnaireResponse: "b14b538f-7de3-4767-ad77-464d755d78bd", //QuestionnaireResponseSchema.schemaUid,
+    ReflexSubmission: "f5cf2d8a-1f78-4f21-b4bd-082e983b830c" //ReflexSubmissionSchema.schemaUid,
+};

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,32 @@
+export interface DialogMessage {
+    type: string;
+    payload?: any;
+    id?: string;
+}
+export type WelshareEnvironment = "development" | "production";
+/**
+ * a welshare schema type uid
+ */
+export type SubmissionSchemaId = string;
+export interface SubmissionPayload<T> {
+    applicationId: string;
+    timestamp: Date;
+    schemaId: SubmissionSchemaId;
+    submission: T;
+}
+export interface DataSubmissionDialogMessage extends DialogMessage {
+    payload: SubmissionPayload<unknown>;
+}
+export interface WelshareConnectionOptions {
+    applicationId: string;
+    apiBaseUrl?: string;
+    environment?: WelshareEnvironment;
+    callbacks: {
+        onUploaded?: (payload: SubmissionPayload<unknown>) => void;
+        onError?: (error: string) => void;
+        onSessionReady?: (sessionPubKey: string) => void;
+        onDialogClosing?: () => void;
+        onDialogReady?: () => void;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,YAAY,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAEvC,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,UAAU,EAAE,CAAC,CAAC;CACf;AAED,MAAM,WAAW,2BAA4B,SAAQ,aAAa;IAChE,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IAEtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,SAAS,EAAE;QACT,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;QAC3D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;QAClC,cAAc,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,IAAI,CAAC;QACjD,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;QAC7B,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;KAC5B,CAAC;CACH"}

package/dist/esm/types.js

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

package/dist/node_modules/@welshare/react/.gitignore

@@ -0,0 +1,6 @@
+.tshy-build
+dist/
+node_modules/
+*.tsbuildinfo
+coverage/
+.vitest/

package/dist/node_modules/@welshare/react/.npmignore

@@ -0,0 +1,34 @@
+# Source files
+src/
+tsconfig.json
+tsconfig.lint.json
+tshy.config.ts
+vitest.config.ts
+
+# Development files
+.github/
+.vscode/
+*.log
+*.tsbuildinfo
+
+# Test files
+__tests__/
+*.test.*
+*.spec.*
+
+# Build artifacts
+.tshy-build/
+coverage/
+.vitest/
+
+# Development dependencies
+node_modules/
+
+# IDE files
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db

package/dist/node_modules/@welshare/react/.tshy/build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "../src",
+    "module": "nodenext",
+    "moduleResolution": "nodenext"
+  }
+}

package/dist/node_modules/@welshare/react/.tshy/esm.json

@@ -0,0 +1,16 @@
+{
+  "extends": "./build.json",
+  "include": [
+    "../src/**/*.ts",
+    "../src/**/*.mts",
+    "../src/**/*.tsx",
+    "../src/**/*.json"
+  ],
+  "exclude": [
+    "../src/**/__tests__/**",
+    "../src/package.json"
+  ],
+  "compilerOptions": {
+    "outDir": "../.tshy-build/esm"
+  }
+}

package/dist/node_modules/@welshare/react/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2025 Welshare Health UG (haftungsbeschränkt) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/node_modules/@welshare/react/README.md

@@ -0,0 +1,124 @@
+# @welshare/react
+
+### Disclaimer, notes on maturity
+
+This library is in Alpha / demo state at this moment. We're using it to review the security aspects while data is in transfer and in rest. There's absolutely no guarantee or warrant that at this point any data is safe. All data can be lost at any time - even though we're using resources that puts decentralization and resilience values to the front. Be **very** careful if you're integrating this into user facing code. Welshare Health wallets are controlled by cryptographic material which _can_ be stored in non custodial / MPC environments (Privy). While that's considered very safe, we can't guarantee at this point that we've already got each aspect of inter application communication or key derivation features right, so don't connect wallets that store significant value with the welshare wallet yet.
+
+## Purpose
+
+This is a React library that helps integrating with Welshare's sovereign data sharing platform. This package provides React hooks and components to connect applications with Welshare's wallet for secure data submission.
+
+## Installation
+
+```bash
+npm install @welshare/react
+# or
+yarn add @welshare/react
+# or
+pnpm add @welshare/react
+```
+
+## Peer Dependencies
+
+This package requires React 19+ as a peer dependency.
+
+## Prerequisites
+
+You need to register an app identifier using the Welshare Wallet frontend first: https://wallet.welshare.app/application. We're referring to this as `your-application-id` from here on.
+
+If you want to submit questionnaire data, your application must first register a new questionnaire definition. You can also reuse an existing questionnaire id to let users contribute responses to another app's questionaire, but that's not highly encouraged at this point.
+
+## Data Submissions
+
+At the moment there are only two supported submission types: Fhir compatible QuestionnaireResponses and our custom "Reflex" app submissions. Both types are identified by schema uids that are accessible on the `Schemas` export.
+
+```
+export const Schemas = {
+  QuestionnaireResponse: "b14b538f-7de3-4767-ad77-464d755d78bd"
+};
+```
+
+To submit questionnaires using custom frontends, you'll use the `useWelshare` hook to open a wallet dialog that lets your application talk to the user's connected wallets (using derived storage keys). All communication with the Welshare infrastructure happens inside that browser window.
+
+## Code Sample
+
+```tsx
+import { ConnectWelshareButton, Schemas, useWelshare } from "@welshare/react";
+
+export function QuestionnaireForm() {
+  const { isConnected, openWallet, submitData } = useWelshare({
+    applicationId: <your-application-id>,
+    environment: "development", //optional, at the moment the environment is always development
+    callbacks: {
+      onUploaded: (payload) => console.log('Data uploaded:', payload),
+      onError: (error) => console.error('Error:', error),
+      onSessionReady: (storageKey) => console.log('Session ready:', storageKey),
+    }
+  });
+
+  const handleSubmit = () => {
+    //response is a QuestionnaireResponse compatible object
+    submitData(Schemas.QuestionnaireResponse, response);
+  };
+
+  // using the `ConnectWelshareButton` is not mandatory. Use your own buttons if you feel like it.
+  return (
+    <div>
+      {!isConnected ? (
+        <ConnectWelshareButton openWallet={openWallet}>
+          Connect to Welshare
+        </ConnectWelshareButton>
+      ) : (
+        <form>
+          {/* ... some form that collects your response data ... */}
+          <button onClick={() => handleSubmit(response)} disabled={isSubmitting}>
+            {isSubmitting ? 'Submitting...' : 'Submit Data'}
+          </button>
+        </form>
+      )}
+    </div>
+  );
+}
+```
+
+## API
+
+### supported callbacks
+
+those are configured in the `useWelshare` options parameter and called back during interactions with the wallet dialog
+
+```tsx
+  callbacks: {
+    onUploaded?: (payload: SubmissionPayload<unknown>) => void;
+    onError?: (error: string) => void;
+    onSessionReady?: (sessionPubKey: string) => void;
+    onDialogClosing?: () => void;
+    onDialogReady?: () => void;
+  }
+```
+
+## Security Notes
+
+No part of this application deals with a "blockchain" directly (Nillion nodes are validated by a custom chain but that's not a fact relevant for end users' security in this scope).
+
+The EVM addresses that control a user profile are (supposedly) never leaked to a third party.
+
+The key derivation mechanism that creates new storage keys that users use to sign messages is not guaranteed to be 100% sound. At this moment it's used as a cryptographic authenticator, but the derivation mechanism will change in the future, rendering already existing keys obsolete. We're not guaranteeing that your key material stays trivially derivable.
+
+Data is stored on [nilDB (by Nillion)](https://docs.nillion.com/build/private-storage/quickstart), a system that can enforces access control, encryption at rest and storage redundancy. While technically possible, the current library does not MPC-encrypt any information. The data is sent to nilDB by a _user client_ that's controlled by the user's own key material. Welshare only delegates NUCs (access rights) to the users. Right now the welshare builder _can_ read any data users upload. This concept will eventually change - welshare's goal is to only make user originated information available inside trusted execution environments.
+
+## Development
+
+This package is built using:
+
+- TypeScript
+- Tshy for build management
+- Vitest for testing
+
+## License
+
+MIT. See the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+Get in touch on Telegram. Check https://welshare.health

package/dist/node_modules/@welshare/react/dist/esm/components/connect-button.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+export declare const ConnectWelshareButton: (props: {
+    openWallet: () => void;
+    children?: React.ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=connect-button.d.ts.map

package/dist/node_modules/@welshare/react/dist/esm/components/connect-button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-button.d.ts","sourceRoot":"","sources":["../../../src/components/connect-button.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,eAAO,MAAM,qBAAqB,UAAW;IAC3C,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,4CAgFA,CAAC"}