Permission API Reference

Use the named Permission, IosPermission, and AndroidPermission constants with the task’s ansight.permissions APIs. They are frozen JavaScript exports with readonly string literal types, so they work with native TypeScript execution. The generated runtime module and declarations include hover docs on every constant.

Usage

Run ansight workspace init . to install ansight/tasks/ansight-task.js and its declarations. Existing support files are preserved by default; --force refreshes canonical files after upgrading the CLI. Nested tasks adjust the relative import path, for example ../ansight-task.js.

import { Permission, IosPermission, AndroidPermission } from "./ansight-task.js";
import type { TaskInvocation } from "./ansight-task.d.ts";

export default async function run({ ansight, expect }: TaskInvocation) {
  await ansight.permissions.grant({ permission: Permission.Microphone });
  const access = await ansight.permissions.query({ permission: Permission.Microphone });
  expect(access.status, { id: "microphone-granted" }).toBe("granted");
  await ansight.permissions.revoke({ permission: Permission.Microphone });

  // Put native calls in tasks for the corresponding platform.
  await ansight.permissions.ios.reset({ permission: IosPermission.Photos });
  await ansight.permissions.android.grant({ permission: AndroidPermission.Camera });
}

Permission, IosPermission, and AndroidPermission can also be used as value types. AppPermission aliases the shared union, and CommonAndroidPermission is the union of the Android constants. AndroidPermission also accepts other fully qualified identifiers, such as "com.example.permission.CUSTOM". Literal strings and the earlier lowercase .names catalogs remain supported.

Platform and operation availability

All operations use the task’s enforced app and session in SDK or device mode; no hostTools declaration or target overrides are needed. Await native calls serially. The Android API levels below describe when a manifest identifier was introduced. Runtime grant/revoke require Android’s runtime-permission mechanism (API 23+), a declared permission managed at runtime, and native policy permitting the change. A constant’s existence does not guarantee effective resource access.

For iOS, mutations require the named service in the installed simctl privacy service list. Xcode 11.4 introduced simctl privacy control. Queries read Simulator TCC or location authorization stores; unrecognized or unreadable state is unknown. The camera service can be queried even when mutations are unavailable. iOS notification control has no backend in this provider. Hardware, global device settings, app capabilities, roles, and usage descriptions are distinct from the authorization state controlled here.

Shared permissions

Each constant maps to the native permissions listed in its row. Android manifest identifiers use the full android.permission. prefix in the linked labels. Calendar, foreground location, and visual media use the subset the app declares. Results expose the exact subset in nativePermissions.

Background location grants the declared Android foreground dependencies first; on API 29+, shared revocation removes only background access. iOS location-always revocation denies all location access. Android 14+ selected photo access can produce limited and is included in shared Photos revocation; grants do not choose which photos or contacts a user shares.

Native iOS permissions

Every row is iOS Simulator only, with no Android native mapping or physical iOS support. Grant/revoke/reset depend on the installed simctl service list. Use shared Permission constants when you want an Android resource equivalent.

reset clears a native authorization decision so the next in-app request can prompt again. Simulator authorization does not supply camera hardware, motion data, media-library content, or Siri behavior.

Native Android permissions

Every row is Android only, on emulators or authorized physical devices. There is no native iOS mapping. The app must declare the identifier and native pm must allow the operation for the active Android user. Shared names provide cross-platform resource approximations where available.

Installer restrictions, account visibility, call/SMS roles, scoped storage, and other native policy are enforced by Android; a pm grant is not a bypass. For custom or additional system permissions, pass a fully qualified identifier. Special access such as overlay, all-files access, and app roles requires other native APIs and is outside these permission methods.

Results and lifecycle

PermissionResult reports supported, isSuccess, status, backend, nativePermissions, and the enforced target identifiers. Status is granted, denied, notDetermined, limited, unsupported, or unknown. Mixed native states are limited. Unsupported queries return a result; unsupported mutations and failed native commands throw. Partial mutations retain individual observed states in the recorded result. A successful command reports subsequently observed state, which can be unknown if the store is unreadable.

Permission changes can terminate the app. Later calls retain the captured session target; use ansight.lifecycle.launch() when a task needs to relaunch it. Native grants can bypass the app’s usage-description checks, so test its actual prompt flow separately. See the task API for the complete host contract.