Permissions

디바이스 권한(클립보드·연락처·앨범·카메라·마이크·위치)의 조회·요청 기능과 권한 에러 클래스를 제공해요.

API 목록

API	설명
getPermission	권한의 현재 상태를 조회해요
requestPermission	권한을 요청하고 결과를 반환해요
openPermissionDialog	권한 설정 다이얼로그를 띄워요

권한 에러 클래스 7종(OpenCameraPermissionError 등)도 함께 제공돼요 — 권한이 필요한 API가 거부됐을 때 이 클래스들의 인스턴스가 던져져요.

withPermission

기능 설명

권한이 필요한 함수를 감싸요. 감싼 함수를 호출하면 먼저 해당 권한을 요청하고, 거부되면 errorClass로 전달한 에러를 던지고, 허용되면 원래 함수를 실행해요.

반환된 함수에는 같은 권한을 조회하는 getPermission()과 권한을 다시 요청하는 openPermissionDialog()가 정적 메서드로 붙어요. 프레임워크 내부의 Clipboard.getText, Device.getPhotos 같은 API가 이 함수로 만들어져서 Clipboard.getText.getPermission() 형태로 권한을 확인할 수 있어요.

타입

Params

function withPermission<T extends (...args: any[]) => any>(
  fn: T, // 권한이 허용된 뒤 실행할 함수
  name: PermissionName, // 요청할 권한 이름
  access: PermissionAccess, // 요청할 접근 종류
  errorClass: new () => PermissionErrorType, // 권한이 거부되면 던질 에러 클래스
): PermissionFunctionWithDialog<T>;

Response

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

에러

코드	설명
errorClass로 전달한 에러	권한 요청 결과가 denied인 경우예요.

예시 코드

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

const captureWithCamera = withPermission(
  () => {
    // 카메라 권한이 허용된 뒤 실행할 로직
  },
  "camera",
  "access",
  OpenCameraPermissionError,
);

try {
  await captureWithCamera();
} catch (error) {
  if (error instanceof OpenCameraPermissionError) {
    // 권한 다이얼로그를 열어 다시 요청할 수 있어요.
    const status = await captureWithCamera.openPermissionDialog();
    console.log(status); // 'allowed' | 'denied'
    return;
  }
  console.error(error);
}

PermissionError

기능 설명

권한 에러의 공통 부모 클래스예요. 여러 권한 에러를 한 번에 처리할 때 error instanceof PermissionError로 확인할 수 있어요. name은 `${methodName} permission error` 형식이에요.

타입

Params

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

Response

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

예시 코드

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("권한이 거부되었어요:", error.message);
    return;
  }
  console.error(error);
}

GetClipboardTextPermissionError

기능 설명

클립보드 읽기 권한이 거부되었을 때 발생하는 에러예요. error instanceof GetClipboardTextPermissionError로 확인할 수 있어요. PermissionError를 상속해요.

타입

class GetClipboardTextPermissionError extends PermissionError {
  name: "getClipboardText permission error";
  message: "클립보드 읽기 권한이 거부되었어요.";
}

예시 코드

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("클립보드 읽기 권한이 없어요.");
  }
}

SetClipboardTextPermissionError

기능 설명

클립보드 쓰기 권한이 거부되었을 때 발생하는 에러예요. error instanceof SetClipboardTextPermissionError로 확인할 수 있어요. PermissionError를 상속해요.

타입

class SetClipboardTextPermissionError extends PermissionError {
  name: "setClipboardText permission error";
  message: "클립보드 쓰기 권한이 거부되었어요.";
}

예시 코드

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

try {
  await Clipboard.setText("복사할 텍스트");
} catch (error) {
  if (error instanceof SetClipboardTextPermissionError) {
    console.warn("클립보드 쓰기 권한이 없어요.");
  }
}

FetchContactsPermissionError

기능 설명

연락처 권한이 거부되었을 때 발생하는 에러예요. error instanceof FetchContactsPermissionError로 확인할 수 있어요. PermissionError를 상속해요.

타입

class FetchContactsPermissionError extends PermissionError {
  name: "fetchContacts permission error";
  message: "연락처 권한이 거부되었어요.";
}

예시 코드

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("연락처 권한이 없어요.");
  }
}

FetchAlbumPhotosPermissionError

기능 설명

사진첩 권한이 거부되었을 때 발생하는 에러예요. error instanceof FetchAlbumPhotosPermissionError로 확인할 수 있어요. PermissionError를 상속해요.

타입

class FetchAlbumPhotosPermissionError extends PermissionError {
  name: "fetchAlbumPhotos permission error";
  message: "사진첩 권한이 거부되었어요.";
}

예시 코드

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("사진첩 권한이 없어요.");
  }
}

GetCurrentLocationPermissionError

기능 설명

위치 권한이 거부되었을 때 발생하는 에러예요. error instanceof GetCurrentLocationPermissionError로 확인할 수 있어요. PermissionError를 상속해요.

타입

class GetCurrentLocationPermissionError extends PermissionError {
  name: "getCurrentLocation permission error";
  message: "위치 권한이 거부되었어요.";
}

예시 코드

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("위치 권한이 없어요.");
  }
}

StartUpdateLocationPermissionError

기능 설명

위치 업데이트 권한이 거부되었을 때 발생하는 에러예요. GetCurrentLocationPermissionError와 같은 클래스를 가리키는 별칭이라서 error instanceof StartUpdateLocationPermissionError는 GetCurrentLocationPermissionError 인스턴스에도 true예요.

타입

const StartUpdateLocationPermissionError = GetCurrentLocationPermissionError;

예시 코드

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("위치 권한이 없어요.");
    }
    cleanup();
  },
});

OpenCameraPermissionError

기능 설명

카메라 권한이 거부되었을 때 발생하는 에러예요. error instanceof OpenCameraPermissionError로 확인할 수 있어요. PermissionError를 상속해요.

타입

class OpenCameraPermissionError extends PermissionError {
  name: "openCamera permission error";
  message: "카메라 권한이 거부되었어요.";
}

예시 코드

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("카메라 권한이 없어요.");
  }
}

PermissionName

기능 설명

권한을 식별하는 이름 타입이에요.

타입

type PermissionName =
  | "clipboard" // 클립보드
  | "contacts" // 연락처
  | "photos" // 사진첩
  | "geolocation" // 위치
  | "camera" // 카메라
  | "microphone"; // 마이크

PermissionAccess

기능 설명

권한의 접근 종류 타입이에요. read/write는 클립보드·연락처·사진첩처럼 읽기/쓰기가 구분되는 권한에, access는 위치·카메라·마이크처럼 구분이 없는 권한에 사용해요.

타입

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

PermissionStatus

기능 설명

권한의 상태 타입이에요. notDetermined는 사용자가 아직 권한 요청에 응답하지 않은 상태예요.

타입

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

PermissionFunctionName

기능 설명

권한 에러가 발생하는 함수 이름 타입이에요. PermissionError의 name을 구성할 때 사용해요.

타입

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

PermissionErrorConstructorParams

기능 설명

PermissionError 생성자에 전달하는 파라미터 타입이에요.

타입

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

PermissionErrorType

기능 설명

withPermission의 errorClass 파라미터가 만들어 내는 에러 인스턴스의 형태예요.

타입

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

GetPermissionFunction

기능 설명

withPermission으로 래핑된 함수에 붙는 getPermission 정적 메서드의 시그니처예요.

타입

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

PermissionDialogFunction

기능 설명

withPermission으로 래핑된 함수에 붙는 openPermissionDialog 정적 메서드의 시그니처예요.

타입

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

PermissionFunctionWithDialog

기능 설명

withPermission이 반환하는 함수 타입이에요. 원래 함수 시그니처에 getPermission/openPermissionDialog 정적 메서드가 더해진 형태예요.

타입

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