@capxul/sdk-react 1.0.0-alpha.12 → 1.0.0-alpha.14

package/dist/index.mjs

@@ -3,8 +3,6 @@ import { createContext, useCallback, useContext, useEffect, useMemo, useRef, use
 import { QueryClient, QueryClientProvider, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { captureExceptionSync, createCapxulClient, isSettingUpLifecycle } from "@capxul/sdk";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { Errors, isCapxulError } from "@capxul/errors";
-import "@capxul/types";
 //#region src/internal/capxul-bootstrap-context.tsx
 const CapxulBootstrapContext = createContext(null);
 function CapxulBootstrapProvider({ value, children }) {
@@ -149,6 +147,159 @@ function CapxulProvider(props) {
 	});
 }
 //#endregion
+//#region ../errors/src/errors.ts
+const CAPXUL_ERROR_CODES = [
+	"NOT_AUTHENTICATED",
+	"EMAIL_DELIVERY_FAILED",
+	"PROFILE_NOT_FOUND",
+	"SMART_ACCOUNT_MISSING",
+	"PLAYER_NOT_FOUND",
+	"ACCOUNT_NOT_FOUND",
+	"PROVIDER_ERROR",
+	"INVALID_INPUT",
+	"ENV_MISSING",
+	"NOT_IMPLEMENTED",
+	"VERIFICATION_REQUIRED",
+	"INSUFFICIENT_BALANCE",
+	"INVALID_RECIPIENT",
+	"ROLE_PERMISSION_DENIED",
+	"TRANSACTION_FAILED",
+	"RATE_LIMITED",
+	"NETWORK_ERROR",
+	"UNKNOWN",
+	"OTP_EXPIRED",
+	"SIGNER_REJECTED",
+	"CANCELLED",
+	"WRONG_STATE"
+];
+var CapxulError$1 = class extends Error {
+	code;
+	details;
+	correlationId;
+	layer;
+	constructor(code, message, options = {}) {
+		super(message, "cause" in options ? { cause: options.cause } : void 0);
+		this.name = "CapxulError";
+		this.code = code;
+		if (options.details !== void 0) this.details = options.details;
+		if (options.correlationId !== void 0) this.correlationId = options.correlationId;
+		if (options.layer !== void 0) this.layer = options.layer;
+	}
+};
+function isCapxulError(value) {
+	return value instanceof CapxulError$1;
+}
+const Errors = {
+	notAuthenticated: (message, opts) => new CapxulError$1("NOT_AUTHENTICATED", message ?? "Not authenticated", opts?.failure_mode ? { details: { failure_mode: opts.failure_mode } } : void 0),
+	emailDeliveryFailed: (detail) => new CapxulError$1("EMAIL_DELIVERY_FAILED", "Failed to send email", { details: { detail } }),
+	profileNotFound: (authUserId) => new CapxulError$1("PROFILE_NOT_FOUND", `Profile not found for user ${authUserId}`, { details: { authUserId } }),
+	smartAccountMissing: (authUserId) => new CapxulError$1("SMART_ACCOUNT_MISSING", "Smart account not provisioned", { details: { authUserId } }),
+	playerNotFound: (playerId) => new CapxulError$1("PLAYER_NOT_FOUND", playerId ? `Openfort player ${playerId} not found` : "Openfort player not found", playerId === void 0 ? void 0 : { details: { playerId } }),
+	accountNotFound: (accountId) => new CapxulError$1("ACCOUNT_NOT_FOUND", accountId ? `Openfort account ${accountId} not found` : "Openfort account not found", accountId === void 0 ? void 0 : { details: { accountId } }),
+	providerError: (provider, operation, cause, opts) => {
+		const details = {
+			provider,
+			operation
+		};
+		if (opts?.failure_mode) details.failure_mode = opts.failure_mode;
+		return new CapxulError$1("PROVIDER_ERROR", `Provider error: ${provider} ${operation}`, {
+			cause,
+			details
+		});
+	},
+	invalidInput: (field, reason) => new CapxulError$1("INVALID_INPUT", `Invalid ${field}: ${reason}`, { details: {
+		field,
+		reason
+	} }),
+	envMissing: (name) => new CapxulError$1("ENV_MISSING", `Environment variable ${name} not configured`, { details: { name } }),
+	notImplemented: (domain, method) => new CapxulError$1("NOT_IMPLEMENTED", `${domain}.${method} is not yet implemented. This feature is planned for a future release.`, { details: {
+		domain,
+		method
+	} }),
+	/**
+	* Sibling factory to {@link Errors.providerError} for the per-state timeout
+	* path in flows (initially ProvisioningFlow's mint_openfort / deploy_safe /
+	* register_indexer `after:` timers). Same `PROVIDER_ERROR` code as
+	* `providerError`, plus a `details.reason: "timeout"` discriminator so
+	* downstream observers can distinguish failure modes without parsing the
+	* message string. The redacted message names the timeout budget; the
+	* native `cause` carries the same information for `reportError` fidelity.
+	*/
+	providerTimeout: (provider, operation, timeoutMs) => new CapxulError$1("PROVIDER_ERROR", `Provider error: ${provider} ${operation} (timeout exceeded ${timeoutMs}ms)`, {
+		details: {
+			provider,
+			operation,
+			reason: "timeout"
+		},
+		cause: /* @__PURE__ */ new Error(`timeout: ${operation} exceeded ${timeoutMs}ms`)
+	}),
+	verificationRequired: (details) => {
+		return new CapxulError$1("VERIFICATION_REQUIRED", "rail" in details ? `Verification is required before ${details.rail} can use ${details.currentKind}.` : `Verification tier ${details.requiredTier} is required.`, { details });
+	},
+	insufficientBalance: (asset, available, required) => new CapxulError$1("INSUFFICIENT_BALANCE", `Insufficient ${asset} balance`, { details: {
+		asset,
+		available,
+		required
+	} }),
+	invalidRecipient: (reason) => new CapxulError$1("INVALID_RECIPIENT", `Invalid recipient: ${reason}`, { details: { reason } }),
+	/**
+	* The org Zodiac Roles modifier REFUSED the spend on-chain (G4 · #547): the
+	* member's role condition (per-tx cap, per-day allowance, allowed recipient,
+	* or membership) was violated, so `execTransactionWithRole` reverted. This is
+	* a PERMISSION denial — explicitly NOT an `INSUFFICIENT_BALANCE` (the treasury
+	* held the funds; the role's authority is what bound). `reason` discriminates
+	* the violated condition (`over_cap` / `daily_cap` / `not_member` /
+	* `disallowed_recipient` / `condition_violation`); leak-safe — no on-chain
+	* identifiers ever enter the details.
+	*/
+	rolePermissionDenied: (details) => new CapxulError$1("ROLE_PERMISSION_DENIED", `Org role denied this spend on-chain (${details.reason}).`, { details: details.operation === void 0 ? { reason: details.reason } : {
+		reason: details.reason,
+		operation: details.operation
+	} }),
+	/**
+	* A transaction (or sponsored UserOp) failed. `details.reason` discriminates
+	* the failure mode for callers that must distinguish a CONFIRMED on-chain
+	* revert (`"onchain_revert"` — the op executed and reverted, e.g. a Zodiac
+	* Roles condition violation) from an inconclusive infra failure. A confirmed
+	* revert is the ONLY mode the org spend port may map to a roles denial.
+	*/
+	transactionFailed: (operation, cause, extra) => new CapxulError$1("TRANSACTION_FAILED", `Transaction failed: ${operation}`, {
+		cause,
+		details: extra?.reason === void 0 ? { operation } : {
+			operation,
+			reason: extra.reason
+		}
+	}),
+	rateLimited: (details) => new CapxulError$1("RATE_LIMITED", "Rate limit exceeded", details === void 0 ? void 0 : { details: { ...details } }),
+	networkError: (operation, cause) => new CapxulError$1("NETWORK_ERROR", `Network error during ${operation}`, {
+		cause,
+		details: { operation }
+	}),
+	unknown: (cause) => new CapxulError$1("UNKNOWN", "Unknown error", { cause }),
+	otpExpired: (details) => new CapxulError$1("OTP_EXPIRED", "Verification code has expired. Request a new one.", details === void 0 ? void 0 : { details: { ...details } }),
+	signerRejected: (details) => new CapxulError$1("SIGNER_REJECTED", "Signer rejected the request.", {
+		cause: details.cause,
+		details: details.reason === void 0 ? { source: details.source } : {
+			source: details.source,
+			reason: details.reason
+		}
+	}),
+	cancelled: (details) => new CapxulError$1("CANCELLED", "Operation was cancelled.", details === void 0 ? void 0 : { details: { ...details } }),
+	/**
+	* Method called from a flow state where its precondition fails (TA16). The
+	* SDK's method API short-circuits with this error before driving the
+	* internal state machine. `currentState` is the Effect-machine snapshot
+	* tag (stringified — substrate is `@effect/experimental/Machine` per
+	* `docs/canon/decisions/state-machine-substrate.md`); `validStates`
+	* enumerates the states the method accepts.
+	*/
+	wrongState: (details) => new CapxulError$1("WRONG_STATE", `${details.method} called from state '${details.currentState}'; valid states: ${details.validStates.join(", ")}`, { details: {
+		...details,
+		validStates: [...details.validStates]
+	} })
+};
+new Set(CAPXUL_ERROR_CODES);
+//#endregion
 //#region src/internal/require-bootstrapped-client.ts
 /**
 * Narrow the bootstrap-nullable client to a ready client inside a query /
@@ -659,12 +810,29 @@ async function invalidateMoneyState(queryClient, input) {
 	await Promise.all(invalidations);
 }
 //#endregion
+//#region src/internal/reject-unresolved-actor.ts
+/**
+* Guard for mutation hooks whose variables carry an optional `actor` field
+* (`useCapxulPay`, `useCapxulPayout`, `useCapxulAddDestination`,
+* `useCapxulRemoveDestination`). Mirrors `requireActorScope` on the query path:
+* an EXPLICITLY-passed `actor: undefined` (the `capxulOrgScope(notYetLoadedOrgId)`
+* footgun) must fail loudly rather than silently fall back to the personal
+* scope. Omitting the `actor` key entirely keeps the personal-scope default.
+*
+* Throws `CapxulError` code `INVALID_INPUT` with `details.field === "actor"`;
+* called inside an async mutationFn it surfaces as `mutation.error: CapxulError`.
+*/
+function rejectUnresolvedActor(variables, operation) {
+	if (Object.hasOwn(variables, "actor") && variables.actor === void 0) throw Errors.invalidInput("actor", `explicitly provided but undefined for ${operation} — actor scope not yet resolved; omit actor for the personal scope`);
+}
+//#endregion
 //#region src/hooks/use-capxul-money.ts
 function useCapxulPay() {
 	const client = useCapxulClientOrNull();
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
+			rejectUnresolvedActor(input, "payments.pay");
 			const bootstrappedClient = requireBootstrappedClient(client, "payments.pay");
 			return unwrapCapxulResult(await bootstrappedClient.payments.pay(input), bootstrappedClient._internal.telemetry, "mutation");
 		},
@@ -682,6 +850,7 @@ function useCapxulPayout() {
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
+			rejectUnresolvedActor(input, "payments.payout");
 			const bootstrappedClient = requireBootstrappedClient(client, "payments.payout");
 			return unwrapCapxulResult(await bootstrappedClient.payments.payout(input), bootstrappedClient._internal.telemetry, "mutation");
 		},
@@ -923,6 +1092,7 @@ function useCapxulAddDestination() {
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
+			rejectUnresolvedActor(input, "destinations.add");
 			const bootstrappedClient = requireBootstrappedClient(client, "destinations.add");
 			return unwrapCapxulResult(await bootstrappedClient.destinations.add(input), bootstrappedClient._internal.telemetry, "mutation");
 		},
@@ -937,6 +1107,7 @@ function useCapxulRemoveDestination() {
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
+			rejectUnresolvedActor(input, "destinations.remove");
 			const bootstrappedClient = requireBootstrappedClient(client, "destinations.remove");
 			return unwrapCapxulResult(await bootstrappedClient.destinations.remove(input), bootstrappedClient._internal.telemetry, "mutation");
 		},
@@ -1344,6 +1515,38 @@ function toQuerySlotState(query) {
 	};
 }
 //#endregion
+//#region ../types/src/index.ts
+const SUPPORTED_CURRENCIES = [
+	{
+		code: "USD",
+		symbol: "$",
+		name: "US Dollar"
+	},
+	{
+		code: "NGN",
+		symbol: "NGN",
+		name: "Nigerian Naira"
+	},
+	{
+		code: "GHS",
+		symbol: "GHS",
+		name: "Ghanaian Cedi"
+	},
+	{
+		code: "KES",
+		symbol: "KSh",
+		name: "Kenyan Shilling"
+	},
+	{
+		code: "UGX",
+		symbol: "USh",
+		name: "Ugandan Shilling"
+	}
+];
+SUPPORTED_CURRENCIES.map((currency) => currency.code);
+Object.fromEntries(SUPPORTED_CURRENCIES.map((currency) => [currency.code, currency.symbol]));
+Math.floor(Number.MAX_SAFE_INTEGER / 1e3);
+//#endregion
 //#region src/headless/money/SendMoney.tsx
 function SendMoney({ initialValue = null, slots, onSent }) {
 	const pay = useCapxulPay();