usePermission
Request an RFC-0002 remote permission from the host
usePermission asks the host to grant one RFC-0002 remote permission, such
as ChainSubmit, StatementSubmit or Remote domain access. Call
request(permission): it resolves to true when the host granted and
false when the user declined. A denial is data, not an exception; thrown
errors mean the request itself failed. The hook also returns mutation state
(isPending, error, data, reset).
You rarely need ChainSubmit, StatementSubmit or PreimageSubmit
explicitly: the corresponding business hooks request them on first use
(useTx requests ChainSubmit on first submit, for
example). Reach for usePermission to front-load the prompt at a natural
moment in your UX, or for permissions with no implicit trigger such as
Remote domains.
This is a host feature: standalone, request rejects with
HostUnavailableError, so gate the affordance on
useIsHost.
Usage
import { useIsHost, usePermission } from "@use-truapi/react";
function EnableApiAccess() {
const isHost = useIsHost();
const { request, isPending, error } = usePermission();
async function onEnable() {
const granted = await request({
tag: "Remote",
value: { domains: ["api.example.com"] },
});
if (!granted) console.warn("user declined API access");
}
if (!isHost) return null;
return (
<>
<button type="button" onClick={onEnable} disabled={isPending}>
{isPending ? "Waiting for approval…" : "Enable API access"}
</button>
{error && <p role="alert">{error.message}</p>}
</>
);
}<script setup lang="ts">
import { useIsHost, usePermission } from "@use-truapi/vue";
const isHost = useIsHost();
const { request, isPending, error } = usePermission();
async function onEnable() {
const granted = await request({
tag: "Remote",
value: { domains: ["api.example.com"] },
});
if (!granted) console.warn("user declined API access");
}
</script>
<template>
<template v-if="isHost">
<button type="button" :disabled="isPending" @click="onEnable">
{{ isPending ? "Waiting for approval…" : "Enable API access" }}
</button>
<p v-if="error" role="alert">{{ error.message }}</p>
</template>
</template>See also
useDevicePermissioncovers device capabilities (camera, notifications, clipboard).useResourceAllocationbatches RFC-0010 allowances into one prompt.useTxrequestsChainSubmitimplicitly on first submit.
API reference
React
function usePermission(options?): NamedMutation<boolean, RemotePermission> & object;RFC-0002 remote permissions (ChainSubmit, StatementSubmit, Remote domains, …): request(permission).
Parameters
| Parameter | Type |
|---|---|
options? | { mutation?: MutationOptions<boolean, RemotePermission>; } |
options.mutation? | MutationOptions<boolean, RemotePermission> |
Returns
NamedMutation<boolean, RemotePermission> & object
Vue
function usePermission(options?): NamedMutation<boolean, RemotePermission> & object;RFC-0002 remote permissions (ChainSubmit, StatementSubmit, Remote domains, …): request(permission).
Parameters
| Parameter | Type |
|---|---|
options? | { mutation?: MutationOptions<boolean, RemotePermission>; } |
options.mutation? | MutationOptions<boolean, RemotePermission> |
Returns
NamedMutation<boolean, RemotePermission> & object