Permissions

Provides functions to query and request device permissions (clipboard, contacts, album, camera, microphone, location) and permission error classes.

API List

API	Description
getPermission	Checks the current status of a permission
requestPermission	Requests a permission and returns the result
openPermissionDialog	Opens the permission settings dialog

Seven permission error classes (OpenCameraPermissionError and more are also provided — when a permission-required API is denied, instances of these classes are thrown.

withPermission

Feature description

Wraps a function that requires permission. When you call the wrapped function, it first requests that permission, and if denied, errorClassit throws the error passed to errorClass, and if allowed, it executes the original function.

The returned function also has getPermission()to query the same permission, and openPermissionDialog()attached as static methods. Inside the framework, Clipboard.getText, Device.getPhotos the same API is built with this function, so Clipboard.getText.getPermission() you can check permissions in this form.

Type

Params

function withPermission<T extends (...args: any[]) => any>(
  fn: T, // Function to run after permission is allowed
  name: PermissionName, // Name of the permission to request
  access: PermissionAccess, // Type of access to request
  errorClass: new () => PermissionErrorType, // Error class to throw if permission is denied
): PermissionFunctionWithDialog<T>;

Response

type PermissionFunctionWithDialog<T extends (...args: any[]) => any> = T & {
  getPermission: GetPermissionFunction;
  openPermissionDialog: PermissionDialogFunction;
};

Error

Code	Description
errorClassThe error passed to	when the permission request result is denieddenied.

Example code

import {
  withPermission,
  OpenCameraPermissionError,
} from "@apps-in-toss/web-framework";

const captureWithCamera = withPermission(
  () => {
    // Logic to run after camera permission is allowed
  },
  "camera",
  "access",
  OpenCameraPermissionError,
);

try {
  await captureWithCamera();
} catch (error) {
  if (error instanceof OpenCameraPermissionError) {
    // You can open the permission dialog and request it again.
    const status = await captureWithCamera.openPermissionDialog();
    console.log(status); // 'allowed' | 'denied'
    return;
  }
  console.error(error);
}

PermissionError

Feature description

This is the common parent class of permission errors. When handling multiple permission errors at once, error instanceof PermissionErrorYou can check it with nameis `${methodName} permission error` format.

Type

Params

interface PermissionErrorConstructorParams {
  methodName: PermissionFunctionName;
  message: string;
}

Response

class PermissionError extends Error {
  name: string; // `${methodName} permission error`
  message: string;
}

Example code

import { Clipboard, PermissionError } from "@apps-in-toss/web-framework";

try {
  const text = await Clipboard.getText();
  console.log(text);
} catch (error) {
  if (error instanceof PermissionError) {
    console.warn("Permission denied:", error.message);
    return;
  }
  console.error(error);
}

GetClipboardTextPermissionError

Feature description

This error occurs when clipboard read permission is denied. error instanceof GetClipboardTextPermissionErrorYou can check it with PermissionErrorextends it.

Type

class GetClipboardTextPermissionError extends PermissionError {
  name: "getClipboardText permission error";
  message: "Clipboard read permission was denied.";
}

Example code

import {
  Clipboard,
  GetClipboardTextPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const text = await Clipboard.getText();
  console.log(text);
} catch (error) {
  if (error instanceof GetClipboardTextPermissionError) {
    console.warn("You don't have clipboard read permission.");
  }
}

SetClipboardTextPermissionError

Feature description

This error occurs when clipboard write permission is denied. error instanceof SetClipboardTextPermissionErrorYou can check it with PermissionErrorextends it.

Type

class SetClipboardTextPermissionError extends PermissionError {
  name: "setClipboardText permission error";
  message: "Clipboard write permission was denied.";
}

Example code

import {
  Clipboard,
  SetClipboardTextPermissionError,
} from "@apps-in-toss/web-framework";

try {
  await Clipboard.setText("Text to copy");
} catch (error) {
  if (error instanceof SetClipboardTextPermissionError) {
    console.warn("You don't have clipboard write permission.");
  }
}

FetchContactsPermissionError

Feature description

This error occurs when contacts permission is denied. error instanceof FetchContactsPermissionErrorYou can check it with PermissionErrorextends it.

Type

class FetchContactsPermissionError extends PermissionError {
  name: "fetchContacts permission error";
  message: "Contacts permission was denied.";
}

Example code

import {
  Device,
  FetchContactsPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const contacts = await Device.getContacts({ size: 10, offset: 0 });
  console.log(contacts);
} catch (error) {
  if (error instanceof FetchContactsPermissionError) {
    console.warn("You don't have contacts permission.");
  }
}

FetchAlbumPhotosPermissionError

Feature description

This error occurs when album permission is denied. error instanceof FetchAlbumPhotosPermissionErrorYou can check it with PermissionErrorextends it.

Type

class FetchAlbumPhotosPermissionError extends PermissionError {
  name: "fetchAlbumPhotos permission error";
  message: "Album permission was denied.";
}

Example code

import {
  Device,
  FetchAlbumPhotosPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const photos = await Device.getPhotos();
  console.log(photos);
} catch (error) {
  if (error instanceof FetchAlbumPhotosPermissionError) {
    console.warn("You don't have album permission.");
  }
}

GetCurrentLocationPermissionError

Feature description

This error occurs when location permission is denied. error instanceof GetCurrentLocationPermissionErrorYou can check it with PermissionErrorextends it.

Type

class GetCurrentLocationPermissionError extends PermissionError {
  name: "getCurrentLocation permission error";
  message: "Location permission was denied.";
}

Example code

import {
  Accuracy,
  Device,
  GetCurrentLocationPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const location = await Device.getLocation({ accuracy: Accuracy.Balanced });
  console.log(location);
} catch (error) {
  if (error instanceof GetCurrentLocationPermissionError) {
    console.warn("No location permission.");
  }
}

StartUpdateLocationPermissionError

Feature description

This error occurs when location update permission is denied. GetCurrentLocationPermissionErrorbecause it is an alias referring to the same class as error instanceof StartUpdateLocationPermissionErroris GetCurrentLocationPermissionError also in the instance true.

Type

const StartUpdateLocationPermissionError = GetCurrentLocationPermissionError;

Example code

import {
  Accuracy,
  Device,
  StartUpdateLocationPermissionError,
} from "@apps-in-toss/web-framework";

const cleanup = Device.subscribeLocation({
  options: {
    accuracy: Accuracy.Balanced,
    timeInterval: 3000,
    distanceInterval: 10,
  },
  onEvent: (location) => {
    console.log(location);
  },
  onError: (error) => {
    if (error instanceof StartUpdateLocationPermissionError) {
      console.warn("No location permission.");
    }
    cleanup();
  },
});

OpenCameraPermissionError

Feature description

This error occurs when camera permission is denied. error instanceof OpenCameraPermissionErrorYou can check it with PermissionErrorextends it.

Type

class OpenCameraPermissionError extends PermissionError {
  name: "openCamera permission error";
  message: "Camera permission was denied.";
}

Example code

import { Device, OpenCameraPermissionError } from "@apps-in-toss/web-framework";

try {
  const image = await Device.openCamera();
  console.log(image);
} catch (error) {
  if (error instanceof OpenCameraPermissionError) {
    console.warn("You don't have camera permission.");
  }
}

PermissionName

Feature description

This is the name type that identifies a permission.

Type

type PermissionName =
  | "clipboard" // clipboard
  | "contacts" // contacts
  | "photos" // album
  | "geolocation" // location
  | "camera" // camera
  | "microphone"; // microphone

PermissionAccess

Feature description

This is the access-type for a permission. read/writeis used for permissions where read/write are separated, such as clipboard, contacts, and album, accessis used for permissions without separate access types, such as location, camera, and microphone.

Type

type PermissionAccess = "read" | "write" | "access";

PermissionStatus

Feature description

This is the status type of a permission. notDeterminedmeans the user has not yet responded to the permission request.

Type

type PermissionStatus = "notDetermined" | "denied" | "allowed";

PermissionFunctionName

Feature description

This is the function-name type where permission errors occur. PermissionErrorof nameUsed when composing

Type

type PermissionFunctionName =
  | "getClipboardText"
  | "setClipboardText"
  | "fetchContacts"
  | "fetchAlbumPhotos"
  | "getCurrentLocation"
  | "openCamera";

PermissionErrorConstructorParams

Feature description

PermissionError This is the parameter type passed to the constructor.

Type

interface PermissionErrorConstructorParams {
  methodName: PermissionFunctionName;
  message: string;
}

PermissionErrorType

Feature description

withPermissionof errorClass This is the shape of the error instance created by the parameters.

Type

interface PermissionErrorType extends Error {
  name: string;
  message: string;
}

GetPermissionFunction

Feature description

withPermissionAttached to a function wrapped with getPermission This is the signature of the static method.

Type

type GetPermissionFunction = () => Promise<PermissionStatus>;

PermissionDialogFunction

Feature description

withPermissionAttached to a function wrapped with openPermissionDialog This is the signature of the static method.

Type

type PermissionDialogFunction = () => Promise<
  Exclude<PermissionStatus, "notDetermined">
>;

PermissionFunctionWithDialog

Feature description

withPermissionThis is the type of function returned by this. It adds getPermission/openPermissionDialog static methods to the original function signature.

Type

type PermissionFunctionWithDialog<T extends (...args: any[]) => any> = T & {
  getPermission: GetPermissionFunction;
  openPermissionDialog: PermissionDialogFunction;
};