@welshare/react 0.2.3 → 0.4.0

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright © 2025 Welshare Health UG (haftungsbeschränkt) 2025
+Copyright © 2025-2026 Welshare Health UG (haftungsbeschränkt) 
 
 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:
 

package/README.md

@@ -2,7 +2,7 @@
 
 ### 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.
+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, even though we're using resources that prioritize decentralization and resilience. 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
 
@@ -32,9 +32,10 @@ If you want to submit questionnaire data, your application must first register a
 
 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.
 
-```
+```js
 export const Schemas = {
-  QuestionnaireResponse: "b14b538f-7de3-4767-ad77-464d755d78bd"
+  QuestionnaireResponse: "b14b538f-7de3-4767-ad77-464d755d78bd",
+  BinaryFile: "9d696baf-483f-4cc0-b748-23a22c1705f5",
 };
 ```
 
@@ -83,47 +84,93 @@ export function QuestionnaireForm() {
 
 ### Binary file uploads (e.g. images)
 
-binary file uploads require a lot of back and forth with the wallet dialog that we wrapped into one convenient upload API. If you want to include binary uploads into your questionnaires, you would typically hook into your own form, upload the file using the `uploadFile` function exposed by the `useWelshare` hook and use the response information to in the respective questionnaire form answer item.
+The package provides two ways to upload binary files:
+
+1. **`useWelshare` hook** - Upload via the wallet dialog (external wallet flow)
+2. **`useBinaryUploads` hook** - Upload directly with your own session keypair
+
+Before data hits any server, the SDK encrypts all files with a new random symmetric AES (GCM / 256 bits) key. Users request a presigned upload url and post the encrypted file to an S3 compatible API that's currently operated by Welshare. Ultimately, they encrypt the encryption key for a Nillion _owned_ BinaryData collection and store it across Nillion nodes (no single node can recover the key). At the time of insertion, they currently also grant ACL read rights for the application (Technically, this is the welshare builder keypair at the moment).
+
+#### Option 1: Upload via Wallet Dialog (`useWelshare`)
 
-Each download should contain a reference to the resource that initiated its upload. As Welshare right now is mostly about questionnaires, you should use a combination of the resource type (questionnaire), the questionnaire id and the answer item's id
+This works best for applications that **don't** manage their own keypairs. It delegates the heavy lifting to the welshare wallet dialog frame.
 
 ```ts
-const reference = `questionnaire/${questionnaireId}/${answerItemId}`;
+const { isConnected, openWallet, uploadFile, submitData } = useWelshare({
+  applicationId: process.env.NEXT_PUBLIC_WELSHARE_APP_ID || "",
+});
+
+// Upload file (wallet dialog handles auth)
+const { url: uploadedFileUrl, binaryFileUid } = await uploadFile(
+  userFile,
+  `questionnaire/${questionnaireId}/${linkId}`
+);
+
+// Use in QuestionnaireResponse
+const responseItem = {
+  answer: [
+    {
+      valueAttachment: {
+        id: binaryFileUid,
+        contentType: userFile.type,
+        size: userFile.size,
+        title: userFile.name,
+        url: uploadedFileUrl,
+      },
+    },
+  ],
+};
 ```
 
-Binary files are addressed as items of type `valueAttachment` in Fhir. See https://www.hl7.org/fhir/questionnaireresponse.html 
-
-Before uploading, welshare encrypts all files with a new random symmetric AES (GCM / 256 bits) key. Users request a presigned upload url and post the encrypted file to an S3 compatible API of ours. Finally, they encrypt the encryption key on a user controlled Nillion *owned* collection for binary data and grant respective access rights for the application. The application a user used to upload the file is by default able to download the file again (Technically, that application is always welshare right now. This will change to the "builder" address of the respective app and the hpmp enclave keys, which allow AI access to the files)
+#### Option 2: Direct Upload (`useBinaryUploads`)
 
-Here's an example how to use it:   
+For applications that manage storage keypairs directly:
 
 ```ts
-  const { isConnected, openWallet, uploadFile, submitData } = useWelshare({
-    applicationId: process.env.NEXT_PUBLIC_WELSHARE_APP_ID || ""
-  })
-  //... let users select a file on their box
-
-  const { url: uploadedFileUrl, binaryFileUid } = await uploadFile(
-    userFile,
-    reference: `questionnaire/${questionnaireId}/<linkId>`
-  );
+import {
+  useBinaryUploads,
+  encryptAndUploadFile,
+  Schemas,
+} from "@welshare/react";
+import { WelshareApi } from "@welshare/sdk";
+
+const { createUploadCredentials, downloadAndDecryptFile, isRunning, error } =
+  useBinaryUploads({
+    keypair: storageKeyPair, // storage keypairs are derived by users
+    environment: "production",
+  });
 
-  const responseItem = {
-    answer = [
-      {
-        valueAttachment: {
-          id: binaryFileUid,
-          contentType: userFile.type,
-          size: userFile.size,
-          title: userFile.name,
-          url: uploadedFileUrl,
-        },
-      },
-    ];
-  }
-  // insert the responseItem into your QuestionnaireResponse
+// Get presigned URL
+const { presignedUrl, uploadKey } = await createUploadCredentials({
+  applicationId: "your-app-id",
+  reference: `questionnaire/${questionnaireId}/photo`,
+  fileName: file.name,
+  fileType: file.type,
+});
+
+// Encrypt & upload to S3, then submit metadata to Nillion
+const { encryptionKey } = await encryptAndUploadFile(file, presignedUrl);
+await WelshareApi.submitBinaryData(
+  storageKeyPair,
+  {
+    encryption_key: JSON.stringify(encryptionKey),
+    reference: `questionnaire/${questionnaireId}/photo`,
+    file_name: file.name,
+    file_size: file.size,
+    file_type: file.type,
+    controller_did: storageKeyPair.toDidString(),
+    url: `welshare://${uploadKey}`,
+  },
+  "production",
+  applicationId
+);
+
+// Download and decrypt owned files
+const decryptedFile = await downloadAndDecryptFile(documentId);
 ```
 
+Binary files are addressed as `valueAttachment` items in FHIR. See https://www.hl7.org/fhir/questionnaireresponse.html
+
 ## API
 
 ### supported callbacks
@@ -143,21 +190,15 @@ those are configured in the `useWelshare` options parameter and called back duri
 
 ## 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.
+No part of this application interacts with a "blockchain" (Nillion nodes are validated by a custom chain but that's relevant for end users' security or privacy).
 
-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.
+The EVM addresses that control a user profile are never disclosed to third parties, hence they cannot correlate the wallet control keys with the keys that control the actual data.
 
-## Development
+The key derivation mechanism is used for creating self signed cryptographic authentication tokens, but the mechanism that keys are derived will very likely change in the future. Existing keys might render obsolete at that point which will require users to manually migrate their data. We don't guarantee that the current key derivation mechanism will be part of this SDK's exposed feature set forever. However, users will always be able to derive keys on their own, as long as they know the rules and don't lose the required secret inputs (e.g. signing keys or salts).
 
-This package is built using:
+Data is stored on [nilDB (by Nillion)](https://docs.nillion.com/build/private-storage/quickstart), a protocol that enforces access control lists, encrypts data at rest and stores records redundantly. Plain data documents are not generally encrypted at this point in time, however. Binary uploads are end to end encrypted in the way that's described above.
 
-- TypeScript
-- Tshy for build management
-- Vitest for testing
+All data that's sent to nilDB via _user client_ is exclusively controlled by the user's own key material. Welshare only delegates NUCs (access rights) to the users. Be aware that right now the welshare builder key _can_ read any data users upload. This will structurally improve once Nillion supports delegated reads for non builder grantees. Welshare's goal is to make user originated information available exclusively for code that runs in execution environments trusted by the users.
 
 ## License
 

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

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

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

@@ -55,8 +55,5 @@ export const ConnectWelshareButton = (props) => {
     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: _jsx(_Fragment, { children: props.children || (_jsxs(_Fragment, { children: [_jsx("span", { className: "", children: _jsx(WelshareLogo, { width: 24, height: 18, style: {
-                                "marginRight": "4px",
-                                color: "#ffffff",
-                            } }) }), _jsx("span", { children: "Connect Welshare Profile" })] })) }) }));
+    return (_jsx("button", { onClick: props.openWallet, style: buttonStyles, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, onMouseDown: handleMouseDown, onFocus: handleFocus, onBlur: handleBlur, type: "button", children: _jsx(_Fragment, { children: props.children || (_jsxs(_Fragment, { children: [_jsx("span", { className: "", children: _jsx(WelshareLogo, { width: 24, height: 18, style: { marginRight: "4px", color: "#ffffff" } }) }), _jsx("span", { children: "Connect Welshare Profile" })] })) }) }));
 };

package/dist/esm/components/welshare-logo.d.ts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React from "react";
 export interface WelshareLogoProps {
     className?: string;
     style?: React.CSSProperties;

package/dist/esm/hooks/use-binary-uploads.d.ts

@@ -0,0 +1,59 @@
+import type { RequestUploadCredentialsPayload, UploadCredentials } from "../types.js";
+import { Nillion, type WelshareApiEnvironment, type WelshareEnvironmentName } from "@welshare/sdk";
+export interface UseBinaryUploadsOptions {
+    /**
+     * The user's session keypair for authentication.
+     */
+    keypair: Nillion.Keypair | null | undefined;
+    /**
+     * The Welshare environment to use for API calls.
+     */
+    environment: WelshareApiEnvironment | WelshareEnvironmentName;
+}
+export interface UseBinaryUploadsResult {
+    /**
+     * Request upload credentials (presigned URL) for uploading an encrypted file.
+     */
+    createUploadCredentials: (payload: RequestUploadCredentialsPayload) => Promise<UploadCredentials>;
+    /**
+     * Download and decrypt a file by its document ID.
+     * Only works for files owned by the current user.
+     */
+    downloadAndDecryptFile: (documentId: string) => Promise<File | undefined>;
+    /**
+     * Whether an operation is currently running.
+     */
+    isRunning: boolean;
+    /**
+     * Error message if the last operation failed.
+     */
+    error: string | null;
+}
+/**
+ * Hook for managing binary file uploads and downloads with Welshare.
+ *
+ * This hook provides functionality to:
+ * - Request presigned URLs for uploading encrypted files to S3
+ * - Download and decrypt files from Nillion storage
+ *
+ * @example
+ * ```tsx
+ * const { createUploadCredentials, downloadAndDecryptFile, isRunning, error } = useBinaryUploads({
+ *   keypair: sessionKeyPair,
+ *   environment: 'production',
+ * });
+ *
+ * // Upload flow: get credentials, encrypt, upload to S3, then submit metadata via submitBinaryData
+ * const credentials = await createUploadCredentials({
+ *   applicationId: 'my-app',
+ *   reference: 'user-photo',
+ *   fileName: 'photo.jpg',
+ *   fileType: 'image/jpeg',
+ * });
+ *
+ * // Download and decrypt
+ * const file = await downloadAndDecryptFile(documentId);
+ * ```
+ */
+export declare const useBinaryUploads: (options: UseBinaryUploadsOptions) => UseBinaryUploadsResult;
+//# sourceMappingURL=use-binary-uploads.d.ts.map

package/dist/esm/hooks/use-binary-uploads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-binary-uploads.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-binary-uploads.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,+BAA+B,EAC/B,iBAAiB,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,OAAO,EAGP,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC7B,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;IAC5C;;OAEG;IACH,WAAW,EAAE,sBAAsB,GAAG,uBAAuB,CAAC;CAC/D;AAED,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,uBAAuB,EAAE,CACvB,OAAO,EAAE,+BAA+B,KACrC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEhC;;;OAGG;IACH,sBAAsB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;IAC1E;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,gBAAgB,YAClB,uBAAuB,KAC/B,sBAuGF,CAAC"}

package/dist/esm/hooks/use-binary-uploads.js

@@ -0,0 +1,93 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { decrypt } from "../lib/encryption.js";
+import { WelshareApi, resolveEnvironment, } from "@welshare/sdk";
+/**
+ * Hook for managing binary file uploads and downloads with Welshare.
+ *
+ * This hook provides functionality to:
+ * - Request presigned URLs for uploading encrypted files to S3
+ * - Download and decrypt files from Nillion storage
+ *
+ * @example
+ * ```tsx
+ * const { createUploadCredentials, downloadAndDecryptFile, isRunning, error } = useBinaryUploads({
+ *   keypair: sessionKeyPair,
+ *   environment: 'production',
+ * });
+ *
+ * // Upload flow: get credentials, encrypt, upload to S3, then submit metadata via submitBinaryData
+ * const credentials = await createUploadCredentials({
+ *   applicationId: 'my-app',
+ *   reference: 'user-photo',
+ *   fileName: 'photo.jpg',
+ *   fileType: 'image/jpeg',
+ * });
+ *
+ * // Download and decrypt
+ * const file = await downloadAndDecryptFile(documentId);
+ * ```
+ */
+export const useBinaryUploads = (options) => {
+    const [isRunning, setIsRunning] = useState(false);
+    const [error, setError] = useState(null);
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    const resolvedEnvironment = useMemo(() => resolveEnvironment(options.environment), [options.environment]);
+    const { keypair } = options;
+    const createUploadCredentials = useCallback(async (payload) => {
+        if (!keypair) {
+            throw new Error("No keypair available");
+        }
+        const { reference, fileName, fileType } = payload;
+        const { presignedUrl, uploadKey } = await WelshareApi.fetchS3WriteDelegation(keypair, { reference, fileName, fileType }, resolvedEnvironment);
+        return { presignedUrl, uploadKey };
+    }, [keypair, resolvedEnvironment]);
+    /**
+     * Downloads and decrypts a file by its document ID from Nillion.
+     */
+    const downloadAndDecryptFile = useCallback(async (documentId) => {
+        if (!keypair) {
+            throw new Error("No keypair available");
+        }
+        try {
+            setIsRunning(true);
+            setError(null);
+            const { binaryFile, data: downloadResponse } = await WelshareApi.fetchBinaryData(keypair, resolvedEnvironment, documentId);
+            const encodedEncryptionKey = JSON.parse(binaryFile.encryption_key);
+            const decryptedData = await decrypt(await downloadResponse, encodedEncryptionKey);
+            if (!decryptedData) {
+                throw new Error("Failed to decrypt file (received null)");
+            }
+            const decryptedFile = new File([decryptedData], binaryFile.file_name, {
+                type: binaryFile.file_type,
+            });
+            return decryptedFile;
+        }
+        catch (err) {
+            console.error("Error during file download/decryption:", err);
+            const errorMessage = err instanceof Error
+                ? err.message
+                : "Failed to download/decrypt file";
+            if (mountedRef.current) {
+                setError(errorMessage);
+            }
+            return undefined;
+        }
+        finally {
+            if (mountedRef.current) {
+                setIsRunning(false);
+            }
+        }
+    }, [keypair, resolvedEnvironment]);
+    return {
+        createUploadCredentials,
+        downloadAndDecryptFile,
+        isRunning,
+        error,
+    };
+};

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

@@ -1 +1 @@
-{"version":3,"file":"use-welshare.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-welshare.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,iBAAiB,EACjB,kBAAkB,EAElB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAIpB,eAAO,MAAM,WAAW,UAAW,yBAAyB;;;;;uBAmLlD,IAAI,aACC,MAAM,KAChB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;iBA0C9B,CAAC,YACT,kBAAkB,cAChB,iBAAiB,CAAC,CAAC,CAAC;;;CAqEnC,CAAC"}
+{"version":3,"file":"use-welshare.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-welshare.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,iBAAiB,EACjB,kBAAkB,EAElB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAQpB,eAAO,MAAM,WAAW,UAAW,yBAAyB;;;;;uBA8LlD,IAAI,aACC,MAAM,KAChB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;iBAuC9B,CAAC,YACT,kBAAkB,cAChB,iBAAiB,CAAC,CAAC,CAAC;;;CAuEnC,CAAC"}

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

@@ -1,3 +1,4 @@
+import { getBaseUrl, WELSHARE_API_ENVIRONMENT, } from "@welshare/sdk/environment";
 import { useEffect, useRef, useState } from "react";
 import { encryptAndUploadFile } from "../lib/uploads.js";
 export const useWelshare = (props) => {
@@ -9,11 +10,15 @@ export const useWelshare = (props) => {
     const [uploadState, setUploadState] = useState();
     // (claude opus) Use ref to control current upload in effect without triggering re-renders
     const currentUploadRef = useRef(null);
+    // Resolve the base URL from environment or apiBaseUrl
+    const resolvedBaseUrl = props.environment
+        ? getBaseUrl(props.environment)
+        : (props.apiBaseUrl ?? getBaseUrl(WELSHARE_API_ENVIRONMENT.production));
     const options = {
-        apiBaseUrl: "https://wallet.welshare.app",
         ...props,
+        apiBaseUrl: resolvedBaseUrl,
     };
-    const WELSHARE_WALLET_URL = `${options.apiBaseUrl}/wallet-external`;
+    const WELSHARE_WALLET_URL = `${resolvedBaseUrl}/wallet-external`;
     useEffect(() => {
         const handleMessage = async (event) => {
             // Verify origin for security
@@ -128,7 +133,13 @@ export const useWelshare = (props) => {
         return () => {
             window.removeEventListener("message", handleMessage);
         };
-    }, [WELSHARE_WALLET_URL, dialogWindow, messageIdCounter, options.applicationId, options.callbacks]);
+    }, [
+        WELSHARE_WALLET_URL,
+        dialogWindow,
+        messageIdCounter,
+        options.applicationId,
+        options.callbacks,
+    ]);
     /**
      * Starts a file upload and returns a promise that resolves with the uploaded file URL
      * @param file The file to upload
@@ -159,10 +170,7 @@ export const useWelshare = (props) => {
             const message = {
                 type: "REQUEST_UPLOAD_CREDENTIALS",
                 id: String(messageIdCounter),
-                payload: {
-                    ...payload,
-                    applicationId: options.applicationId,
-                },
+                payload: { ...payload, applicationId: options.applicationId },
             };
             dialogWindow.postMessage(message, WELSHARE_WALLET_URL);
             setMessageIdCounter((prev) => prev + 1);
@@ -207,7 +215,7 @@ export const useWelshare = (props) => {
                 .filter(([_, value]) => value !== undefined && value !== null)
                 .map(([key, value]) => `social.${key}=${encodeURIComponent(String(value))}`);
             if (socialEntries.length > 0) {
-                socialParams = `&${socialEntries.join('&')}`;
+                socialParams = `&${socialEntries.join("&")}`;
             }
         }
         const walletUrl = `${WELSHARE_WALLET_URL}?applicationId=${options.applicationId}${socialParams}`;

package/dist/esm/index.d.ts

@@ -1,7 +1,9 @@
 export { ConnectWelshareButton } from "./components/connect-button.js";
 export { WelshareLogo } from "./components/welshare-logo.js";
 export { useWelshare } from "./hooks/use-welshare.js";
-export { decrypt, encodeEncryptionKey, encryptFile, generateRandomAESKey } from "./lib/encryption.js";
+export { useBinaryUploads, type UseBinaryUploadsOptions, type UseBinaryUploadsResult, } from "./hooks/use-binary-uploads.js";
+export { WELSHARE_API_ENVIRONMENT, resolveEnvironment, getBaseUrl, type WelshareApiEnvironment, type WelshareEnvironmentName, type NillionClusterConfig, } from "@welshare/sdk/environment";
+export { decrypt, encodeEncryptionKey, encryptFile, generateRandomAESKey, } from "./lib/encryption.js";
 export { decodeEncryptionKey, type EncryptionKey } from "./utils.js";
 export { browserDownload, encryptAndUploadFile } from "./lib/uploads.js";
 export declare const Schemas: {

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EACL,OAAO,EACP,mBAAmB,EACnB,WAAW,EACX,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAErE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAEzE,eAAO,MAAM,OAAO;;;;CAInB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,UAAU,EACV,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,GAC1B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,OAAO,EACP,mBAAmB,EACnB,WAAW,EACX,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAErE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGzE,eAAO,MAAM,OAAO;;;;CAInB,CAAC"}

package/dist/esm/index.js

@@ -1,13 +1,16 @@
-//todo: this is not tree shaken and leaks nillion dependencies transitively. Consider pulling it up
-//import { QuestionnaireResponseSchema, ReflexSubmissionSchema } from "@welshare/sdk";
+// ---- Components ----
 export { ConnectWelshareButton } from "./components/connect-button.js";
 export { WelshareLogo } from "./components/welshare-logo.js";
-// ---- hooks ----
+// ---- Hooks ----
 export { useWelshare } from "./hooks/use-welshare.js";
-export { decrypt, encodeEncryptionKey, encryptFile, generateRandomAESKey } from "./lib/encryption.js";
+export { useBinaryUploads, } from "./hooks/use-binary-uploads.js";
+// ---- Environment (re-exported from @welshare/sdk) ----
+export { WELSHARE_API_ENVIRONMENT, resolveEnvironment, getBaseUrl, } from "@welshare/sdk/environment";
+// ---- Utils ----
+export { decrypt, encodeEncryptionKey, encryptFile, generateRandomAESKey, } from "./lib/encryption.js";
 export { decodeEncryptionKey } from "./utils.js";
 export { browserDownload, encryptAndUploadFile } from "./lib/uploads.js";
-//todo: import them from the SDK or a dedicated SDK constants export
+//todo: import them from the SDK
 export const Schemas = {
     QuestionnaireResponse: "b14b538f-7de3-4767-ad77-464d755d78bd", //QuestionnaireResponseSchema.schemaUid,
     ReflexSubmission: "f5cf2d8a-1f78-4f21-b4bd-082e983b830c", //ReflexSubmissionSchema.schemaUid,

package/dist/esm/lib/encryption.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../../../src/lib/encryption.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,aAAa,EAAuB,MAAM,aAAa,CAAC;AAE5E,eAAO,MAAM,oBAAoB,QAAa,OAAO,CAAC,SAAS,CAU9D,CAAC;AAIF,eAAO,MAAM,WAAW,SAChB,IAAI,OACL,SAAS,KACb,OAAO,CAAC;IAAE,aAAa,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAE,CAgBxD,CAAC;AAEF,eAAO,MAAM,mBAAmB,QACzB,SAAS,MACV,UAAU,KACb,OAAO,CAAC,aAAa,CAgBvB,CAAC;AAGF,eAAO,MAAM,OAAO,kBACH,WAAW,iBACX,aAAa,KAC3B,OAAO,CAAC,WAAW,GAAG,IAAI,CA0B5B,CAAC"}
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../../../src/lib/encryption.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,aAAa,EAAuB,MAAM,aAAa,CAAC;AAE5E,eAAO,MAAM,oBAAoB,QAAa,OAAO,CAAC,SAAS,CAU9D,CAAC;AAIF,eAAO,MAAM,WAAW,SAChB,IAAI,OACL,SAAS,KACb,OAAO,CAAC;IAAE,aAAa,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAE,CAaxD,CAAC;AAEF,eAAO,MAAM,mBAAmB,QACzB,SAAS,MACV,UAAU,KACb,OAAO,CAAC,aAAa,CAYvB,CAAC;AAGF,eAAO,MAAM,OAAO,kBACH,WAAW,iBACX,aAAa,KAC3B,OAAO,CAAC,WAAW,GAAG,IAAI,CAuB5B,CAAC"}

package/dist/esm/lib/encryption.js

@@ -15,10 +15,7 @@ export const encryptFile = async (file, key) => {
     const fileData = await file.arrayBuffer();
     const iv = window.crypto.getRandomValues(new Uint8Array(12));
     // Encrypt the file data
-    const encryptedData = await window.crypto.subtle.encrypt({
-        name: ALGORITHM,
-        iv: iv,
-    }, key, fileData);
+    const encryptedData = await window.crypto.subtle.encrypt({ name: ALGORITHM, iv: iv }, key, fileData);
     return { encryptedData, iv };
 };
 export const encodeEncryptionKey = async (key, iv) => {
@@ -30,21 +27,14 @@ export const encodeEncryptionKey = async (key, iv) => {
     const ivHex = Array.from(iv)
         .map((b) => b.toString(16).padStart(2, "0"))
         .join("");
-    return {
-        algorithm: ALGORITHM,
-        key: keyHex,
-        iv: ivHex,
-    };
+    return { algorithm: ALGORITHM, key: keyHex, iv: ivHex };
 };
 // Helper function to decrypt a file using encoded encryption key
 export const decrypt = async (encryptedData, encryptionKey) => {
     try {
         const { key: keyBytes, iv } = decodeEncryptionKey(encryptionKey);
         const key = await window.crypto.subtle.importKey("raw", keyBytes, { name: ALGORITHM }, false, ["decrypt"]);
-        const decryptedData = await window.crypto.subtle.decrypt({
-            name: ALGORITHM,
-            iv: iv,
-        }, key, encryptedData);
+        const decryptedData = await window.crypto.subtle.decrypt({ name: ALGORITHM, iv: iv }, key, encryptedData);
         return decryptedData;
     }
     catch (error) {

package/dist/esm/lib/uploads.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["../../../src/lib/uploads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAO3C,eAAO,MAAM,oBAAoB,SACzB,IAAI,gBACI,MAAM,KACnB,OAAO,CAAC,aAAa,CAkBvB,CAAC;AAEF,eAAO,MAAM,eAAe,kBAAmB,IAAI,SASlD,CAAA"}
+{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["../../../src/lib/uploads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAO3C,eAAO,MAAM,oBAAoB,SACzB,IAAI,gBACI,MAAM,KACnB,OAAO,CAAC,aAAa,CAgBvB,CAAC;AAEF,eAAO,MAAM,eAAe,kBAAmB,IAAI,SASlD,CAAC"}

package/dist/esm/lib/uploads.js

@@ -6,9 +6,7 @@ export const encryptAndUploadFile = async (file, presignedUrl) => {
     const uploadResponse = await fetch(presignedUrl, {
         method: "PUT",
         body: encryptedData,
-        headers: {
-            "Content-Type": file.type,
-        },
+        headers: { "Content-Type": file.type },
     });
     if (!uploadResponse.ok) {
         throw new Error(`Failed to upload file ${uploadResponse.status}`);

package/dist/esm/types.d.ts

@@ -1,4 +1,5 @@
 import { EncryptionKey } from "./utils.js";
+import type { WelshareApiEnvironment, WelshareEnvironmentName } from "@welshare/sdk/environment";
 export interface DialogMessage {
     type: string;
     payload?: any;
@@ -52,6 +53,16 @@ export interface WelshareConnectionOptions {
         privy?: string;
         twitter?: string;
     };
+    /**
+     * The Welshare environment to connect to.
+     * Can be an environment name ('production', 'staging', etc.) or a full environment object.
+     * Takes precedence over apiBaseUrl if both are provided.
+     */
+    environment?: WelshareApiEnvironment | WelshareEnvironmentName;
+    /**
+     * @deprecated Use `environment` instead for type-safe configuration.
+     * The base URL of the Welshare API. Defaults to production.
+     */
     apiBaseUrl?: string;
     callbacks: {
         onFileUploaded?: (insertedUid: string, url: string) => void;

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;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,MAAM,iBAAiB,GAAG;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAA;AAED,MAAM,WAAW,+BAA+B;IAC9C,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,2BAA4B,SAAQ,+BAA+B;IAClF,aAAa,EAAE,aAAa,CAAC;IAE7B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,iBAAkB,SAAQ,+BAA+B;IACxE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,IAAI,EAAE,IAAI,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE;QACb,OAAO,EAAE,CAAC,MAAM,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,aAAa,EAAE,MAAM,CAAA;SAAE,KAAK,IAAI,CAAC;QAClE,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;KAChC,CAAC;CACH;AAED,MAAM,WAAW,2BAA4B,SAAQ,aAAa;IAChE,OAAO,EACH,iBAAiB,CAAC,OAAO,CAAC,GAC1B,2BAA2B,GAC3B,+BAA+B,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAA;IAED,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE;QACT,cAAc,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAC5D,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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EACV,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAExC,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,MAAM,iBAAiB,GAAG;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E,MAAM,WAAW,+BAA+B;IAC9C,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,2BACf,SAAQ,+BAA+B;IACvC,aAAa,EAAE,aAAa,CAAC;IAE7B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,iBAAkB,SAAQ,+BAA+B;IACxE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,IAAI,EAAE,IAAI,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE;QACb,OAAO,EAAE,CAAC,MAAM,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,aAAa,EAAE,MAAM,CAAA;SAAE,KAAK,IAAI,CAAC;QAClE,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;KAChC,CAAC;CACH;AAED,MAAM,WAAW,2BAA4B,SAAQ,aAAa;IAChE,OAAO,EACH,iBAAiB,CAAC,OAAO,CAAC,GAC1B,2BAA2B,GAC3B,+BAA+B,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF;;;;OAIG;IACH,WAAW,CAAC,EAAE,sBAAsB,GAAG,uBAAuB,CAAC;IAC/D;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE;QACT,cAAc,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAC5D,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/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS,YAAY,CAAC;AACnC,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC;AAElC,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,eAAO,MAAM,mBAAmB,kBACf,aAAa,KAC3B;IAAE,GAAG,EAAE,YAAY,CAAC;IAAC,EAAE,EAAE,YAAY,CAAA;CAUvC,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS,YAAY,CAAC;AACnC,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC;AAElC,MAAM,MAAM,aAAa,GAAG;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E,eAAO,MAAM,mBAAmB,kBACf,aAAa,KAC3B;IAAE,GAAG,EAAE,YAAY,CAAC;IAAC,EAAE,EAAE,YAAY,CAAA;CAUvC,CAAC"}

package/dist/node_modules/@welshare/react/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> @welshare/react@0.3.0 build /Users/stadolf/work/welshare/workspace/surveys-monorepo/packages/welshare-react
+> tshy
+

package/dist/node_modules/@welshare/react/.turbo/turbo-lint.log

@@ -0,0 +1,14 @@
+
+> @welshare/react@0.3.0 lint /Users/stadolf/work/welshare/workspace/surveys-monorepo/packages/welshare-react
+> eslint . --max-warnings 25
+
+
+/Users/stadolf/work/welshare/workspace/surveys-monorepo/packages/welshare-react/src/hooks/use-welshare.ts
+  110:11  warning  Unexpected lexical declaration in case block  no-case-declarations
+  290:19  warning  '_' is defined but never used                 @typescript-eslint/no-unused-vars
+
+/Users/stadolf/work/welshare/workspace/surveys-monorepo/packages/welshare-react/src/types.ts
+  9:13  warning  Unexpected any. Specify a different type  @typescript-eslint/no-explicit-any
+
+✖ 3 problems (0 errors, 3 warnings)
+

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

@@ -1,4 +1,4 @@
-Copyright © 2025 Welshare Health UG (haftungsbeschränkt) 2025
+Copyright © 2025-2026 Welshare Health UG (haftungsbeschränkt) 
 
 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: