@capxul/sandbox 1.0.0-alpha.1 → 1.0.0-alpha.2

package/dist/main.mjs

@@ -498,8 +498,8 @@ async function mintNextjsQuickstartKey(input, deps = {}) {
 //#endregion
 //#region src/runtime.ts
 const bundledPackageVersions = {
-	sdk: "1.0.0-alpha.11",
-	"sdk-react": "1.0.0-alpha.11"
+	sdk: "1.0.0-alpha.14",
+	"sdk-react": "1.0.0-alpha.14"
 };
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const FAUCET_DECIMALS = 6n;
@@ -570,10 +570,28 @@ function createConvexPathRunner({ deployment, env: sourceEnv = process.env, spaw
 		};
 	};
 }
-function normalizeEvmAddress(value) {
-	const address = value.trim();
-	if (!EVM_ADDRESS_PATTERN.test(address)) throw new Error("Address must be a 0x-prefixed 20-byte EVM address.");
-	return address;
+const ORG_HANDLE_SHAPE_PATTERN = /^[a-zA-Z0-9-]+$/;
+/**
+* Classify a faucet recipient prompt value: Capxul email, @org-handle, or —
+* as an explicit escape hatch — a raw EVM address. Canonical normalization
+* (email lowercasing, handle validation) is left to the backend resolver.
+*/
+function parseFaucetRecipient(value) {
+	const trimmed = value.trim();
+	if (EVM_ADDRESS_PATTERN.test(trimmed)) return {
+		kind: "address",
+		address: trimmed
+	};
+	if (trimmed.indexOf("@") > 0) return {
+		kind: "email",
+		email: trimmed
+	};
+	const orgHandle = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+	if (orgHandle.length > 0 && !orgHandle.toLowerCase().startsWith("0x") && ORG_HANDLE_SHAPE_PATTERN.test(orgHandle)) return {
+		kind: "orgHandle",
+		orgHandle
+	};
+	throw new Error("Recipient must be a Capxul email, @org-handle, or 0x address (escape hatch).");
 }
 function usdAmountToBaseUnits(value) {
 	const amount = value.trim();
@@ -602,7 +620,20 @@ function canonicalConvexRunner(env = process.env) {
 //#endregion
 //#region src/commands/faucet-send.ts
 const DEFAULT_FAUCET_AMOUNT = "10";
-const FAUCET_FUNCTION = "dev/faucetMintTo:mintTo";
+const FAUCET_ADDRESS_FUNCTION = "dev/faucetMintTo:mintTo";
+const FAUCET_RECIPIENT_FUNCTION = "dev/faucetMintTo:mintToRecipient";
+function recipientLabel(recipient) {
+	switch (recipient.kind) {
+		case "address": return recipient.address;
+		case "email": return recipient.email;
+		case "orgHandle": return `@${recipient.orgHandle}`;
+	}
+}
+function mintFailureMessage(recipient, output) {
+	const message = output.length > 0 ? output : "Faucet mint failed.";
+	if (recipient.kind === "orgHandle" && message.includes("INVALID_INPUT")) return [message, "Hint: personal payee handles are owner-scoped and cannot be funded by the faucet — use a Capxul email or an org handle."].join("\n");
+	return message;
+}
 async function runFaucetSend() {
 	intro("Capxul sandbox faucet send");
 	note([
@@ -611,20 +642,21 @@ async function runFaucetSend() {
 		"Asset: test USDX, 6 decimals",
 		"This command calls the canonical backend dev faucet and cannot select live/mainnet."
 	].join("\n"), "Canonical sandbox");
-	const addressPrompt = await text({
-		message: "Recipient EVM address",
+	const recipientPrompt = await text({
+		message: "Recipient (Capxul email or @org-handle)",
 		validate(value) {
 			try {
-				normalizeEvmAddress(value ?? "");
+				parseFaucetRecipient(value ?? "");
 			} catch (error) {
 				return errorMessage(error);
 			}
 		}
 	});
-	if (isCancel(addressPrompt)) {
+	if (isCancel(recipientPrompt)) {
 		cancel("No faucet funds sent.");
 		return 0;
 	}
+	const recipient = parseFaucetRecipient(recipientPrompt);
 	const amountPrompt = await text({
 		message: "USDX amount",
 		initialValue: DEFAULT_FAUCET_AMOUNT,
@@ -640,11 +672,21 @@ async function runFaucetSend() {
 		cancel("No faucet funds sent.");
 		return 0;
 	}
-	const holderAddress = normalizeEvmAddress(addressPrompt);
 	const rawAmount = usdAmountToBaseUnits(amountPrompt);
 	const displayAmount = amountPrompt.trim();
+	const identity = recipientLabel(recipient);
+	if (recipient.kind === "address") {
+		const escapeHatch = await confirm({
+			message: `Raw-address escape hatch — this skips Capxul identity resolution. Fund ${identity} directly?`,
+			initialValue: false
+		});
+		if (isCancel(escapeHatch) || escapeHatch === false) {
+			cancel("No faucet funds sent.");
+			return 0;
+		}
+	}
 	const shouldSend = await confirm({
-		message: `Mint ${displayAmount} test USDX to ${holderAddress}?`,
+		message: `Mint ${displayAmount} test USDX to ${identity}?`,
 		initialValue: true
 	});
 	if (isCancel(shouldSend) || shouldSend === false) {
@@ -654,19 +696,29 @@ async function runFaucetSend() {
 	const s = spinner();
 	s.start("Minting testnet funds");
 	try {
-		const result = canonicalConvexRunner(loadOperatorEnv())("", [
+		const runConvex = canonicalConvexRunner(loadOperatorEnv());
+		const result = recipient.kind === "address" ? runConvex("", [
+			"run",
+			FAUCET_ADDRESS_FUNCTION,
+			JSON.stringify({
+				holderAddress: recipient.address,
+				rawAmount
+			})
+		]) : runConvex("", [
 			"run",
-			FAUCET_FUNCTION,
+			FAUCET_RECIPIENT_FUNCTION,
 			JSON.stringify({
-				holderAddress,
+				recipient,
 				rawAmount
 			})
 		]);
-		if (!result.ok) throw new Error(result.output || "Faucet mint failed.");
+		if (!result.ok) throw new Error(mintFailureMessage(recipient, result.output));
 		const txHash = extractField(result.output, "txHash");
+		const safeAddress = recipient.kind === "address" ? recipient.address : extractField(result.output, "safeAddress");
 		s.stop("Faucet funds sent");
 		note([
-			`Recipient: ${holderAddress}`,
+			`Recipient: ${identity}`,
+			`Safe address: ${safeAddress}`,
 			`Amount: ${displayAmount} USDX`,
 			`Raw amount: ${rawAmount}`,
 			`Chain: Base Sepolia (84532)`,
@@ -784,7 +836,7 @@ const SANDBOX_COMMANDS = [{
 	value: "faucet send",
 	label: "Send testnet faucet funds",
 	usage: "npx @capxul/sandbox faucet send",
-	description: "Mint test USDX to an EVM address on Base Sepolia.",
+	description: "Mint test USDX to a Capxul identity (email or org handle) on Base Sepolia.",
 	run: runFaucetSend
 }];
 const HELP_COMMANDS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sandbox",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "private": false,
   "description": "Capxul sandbox CLI for canonical quickstart keys and testnet faucet funds.",
   "keywords": [