@welshare/react 0.2.3 → 0.4.0

package/dist/node_modules/@welshare/react/src/hooks/use-binary-uploads.ts

@@ -0,0 +1,181 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { decrypt } from "../lib/encryption.js";
+import { type EncryptionKey } from "../utils.js";
+import type {
+  RequestUploadCredentialsPayload,
+  UploadCredentials,
+} from "../types.js";
+import {
+  Nillion,
+  WelshareApi,
+  resolveEnvironment,
+  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 const useBinaryUploads = (
+  options: UseBinaryUploadsOptions
+): UseBinaryUploadsResult => {
+  const [isRunning, setIsRunning] = useState(false);
+  const [error, setError] = useState<string | null>(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: RequestUploadCredentialsPayload
+    ): Promise<UploadCredentials> => {
+      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: string): Promise<File | undefined> => {
+      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: EncryptionKey = 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/node_modules/@welshare/react/src/hooks/use-welshare.ts

@@ -8,6 +8,10 @@ import {
   UploadCredentials,
   WelshareConnectionOptions,
 } from "@/types.js";
+import {
+  getBaseUrl,
+  WELSHARE_API_ENVIRONMENT,
+} from "@welshare/sdk/environment";
 import { useEffect, useRef, useState } from "react";
 import { encryptAndUploadFile } from "../lib/uploads.js";
 
@@ -24,12 +28,17 @@ export const useWelshare = (props: WelshareConnectionOptions) => {
   // (claude opus) Use ref to control current upload in effect without triggering re-renders
   const currentUploadRef = useRef<RunningFileUpload>(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: WelshareConnectionOptions = {
-    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: MessageEvent<DialogMessage>) => {
@@ -181,7 +190,13 @@ export const useWelshare = (props: WelshareConnectionOptions) => {
     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
@@ -219,10 +234,7 @@ export const useWelshare = (props: WelshareConnectionOptions) => {
       const message: DialogMessage = {
         type: "REQUEST_UPLOAD_CREDENTIALS",
         id: String(messageIdCounter),
-        payload: {
-          ...payload,
-          applicationId: options.applicationId,
-        },
+        payload: { ...payload, applicationId: options.applicationId },
       };
 
       dialogWindow.postMessage(message, WELSHARE_WALLET_URL);
@@ -276,10 +288,12 @@ export const useWelshare = (props: WelshareConnectionOptions) => {
     if (options.interpolateSocials) {
       const socialEntries = Object.entries(options.interpolateSocials)
         .filter(([_, value]) => value !== undefined && value !== null)
-        .map(([key, value]) => `social.${key}=${encodeURIComponent(String(value))}`);
-      
+        .map(
+          ([key, value]) => `social.${key}=${encodeURIComponent(String(value))}`
+        );
+
       if (socialEntries.length > 0) {
-        socialParams = `&${socialEntries.join('&')}`;
+        socialParams = `&${socialEntries.join("&")}`;
       }
     }
 

package/dist/node_modules/@welshare/react/src/index.ts

@@ -1,20 +1,37 @@
-//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 {
+  useBinaryUploads,
+  type UseBinaryUploadsOptions,
+  type UseBinaryUploadsResult,
+} from "./hooks/use-binary-uploads.js";
 
+// ---- Environment (re-exported from @welshare/sdk) ----
+export {
+  WELSHARE_API_ENVIRONMENT,
+  resolveEnvironment,
+  getBaseUrl,
+  type WelshareApiEnvironment,
+  type WelshareEnvironmentName,
+  type NillionClusterConfig,
+} from "@welshare/sdk/environment";
+
+// ---- Utils ----
 export {
   decrypt,
   encodeEncryptionKey,
   encryptFile,
-  generateRandomAESKey
+  generateRandomAESKey,
 } from "./lib/encryption.js";
 export { decodeEncryptionKey, type EncryptionKey } 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/node_modules/@welshare/react/src/lib/encryption.ts

@@ -24,10 +24,7 @@ export const encryptFile = async (
 
   // Encrypt the file data
   const encryptedData = await window.crypto.subtle.encrypt(
-    {
-      name: ALGORITHM,
-      iv: iv,
-    },
+    { name: ALGORITHM, iv: iv },
     key,
     fileData
   );
@@ -49,11 +46,7 @@ export const encodeEncryptionKey = async (
     .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
@@ -73,10 +66,7 @@ export const decrypt = async (
     );
 
     const decryptedData = await window.crypto.subtle.decrypt(
-      {
-        name: ALGORITHM,
-        iv: iv as BufferSource,
-      },
+      { name: ALGORITHM, iv: iv as BufferSource },
       key,
       encryptedData
     );

package/dist/node_modules/@welshare/react/src/lib/uploads.ts

@@ -16,9 +16,7 @@ export const encryptAndUploadFile = async (
   const uploadResponse = await fetch(presignedUrl, {
     method: "PUT",
     body: encryptedData,
-    headers: {
-      "Content-Type": file.type,
-    },
+    headers: { "Content-Type": file.type },
   });
 
   if (!uploadResponse.ok) {
@@ -37,4 +35,4 @@ export const browserDownload = (decryptedFile: File) => {
   a.click();
   document.body.removeChild(a);
   window.URL.revokeObjectURL(downloadUrl);
-}
+};

package/dist/node_modules/@welshare/react/src/types.ts

@@ -1,4 +1,8 @@
 import { EncryptionKey } from "./utils.js";
+import type {
+  WelshareApiEnvironment,
+  WelshareEnvironmentName,
+} from "@welshare/sdk/environment";
 
 export interface DialogMessage {
   type: string;
@@ -9,7 +13,7 @@ export interface DialogMessage {
 /**
  * a welshare schema type uid
  */
-export type SubmissionSchemaId = string 
+export type SubmissionSchemaId = string;
 
 export interface SubmissionPayload<T> {
   applicationId: string;
@@ -18,10 +22,7 @@ export interface SubmissionPayload<T> {
   submission: T;
 }
 
-export type UploadCredentials = {
-  presignedUrl: string;
-  uploadKey: string;
-}
+export type UploadCredentials = { presignedUrl: string; uploadKey: string };
 
 export interface RequestUploadCredentialsPayload {
   timestamp?: Date;
@@ -31,7 +32,8 @@ export interface RequestUploadCredentialsPayload {
   fileType: string;
 }
 
-export interface BinaryFileSubmissionPayload extends RequestUploadCredentialsPayload {
+export interface BinaryFileSubmissionPayload
+  extends RequestUploadCredentialsPayload {
   encryptionKey: EncryptionKey;
   /// in bytes
   fileSize: number;
@@ -49,8 +51,8 @@ export interface RunningFileUpload extends RequestUploadCredentialsPayload {
 }
 
 export interface DataSubmissionDialogMessage extends DialogMessage {
-  payload: 
-    | SubmissionPayload<unknown> 
+  payload:
+    | SubmissionPayload<unknown>
     | BinaryFileSubmissionPayload
     | RequestUploadCredentialsPayload;
 }
@@ -61,8 +63,17 @@ export interface WelshareConnectionOptions {
     emailAddress?: string;
     privy?: string;
     twitter?: string;
-  }
-  //todo: must go into build config, not supposed to be used by users
+  };
+  /**
+   * 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/node_modules/@welshare/react/src/utils.ts

@@ -1,11 +1,7 @@
 export const ALGORITHM = "AES-GCM";
 export type Algorithm = "AES-GCM";
 
-export type EncryptionKey = {
-  algorithm: Algorithm;
-  key: string;
-  iv: string;
-};
+export type EncryptionKey = { algorithm: Algorithm; key: string; iv: string };
 
 export const decodeEncryptionKey = (
   encryptionKey: EncryptionKey

package/dist/node_modules/@welshare/react/tsconfig.json

@@ -2,20 +2,11 @@
   "extends": "@workspace/typescript-config/react-library.json",
   "compilerOptions": {
     "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"],
-      "@/types/*": ["./types/*"],
-    },
-    "plugins": [
-    ],
+    "paths": { "@/*": ["./src/*"], "@/types/*": ["./types/*"] },
+    "plugins": [],
     "allowJs": true,
     "jsx": "react-jsx"
   },
-  "include": [
-    "next-env.d.ts",
-    "next.config.ts",
-    "**/*.ts",
-    "**/*.tsx",
-  ],
+  "include": ["next-env.d.ts", "next.config.ts", "**/*.ts", "**/*.tsx"],
   "exclude": ["node_modules"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@welshare/react",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "description": "React library for integrating with Welshare's sovereign data sharing platform",
   "keywords": [
     "react",
@@ -22,6 +22,9 @@
   },
   "homepage": "https://welshare.health",
   "type": "module",
+  "dependencies": {
+    "@welshare/sdk": "0.2.0"
+  },
   "peerDependencies": {
     "react": "^19",
     "react-dom": "^19"
@@ -81,7 +84,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20.0.0"
+    "node": "^22.0.0"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 25",