> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/permissions.md).

# Permissions

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

### API 목록

| API                                                                                          | 설명                |
| -------------------------------------------------------------------------------------------- | ----------------- |
| [`getPermission`](/documentation/sdk/domains-api/permissions/getpermission.md)               | 권한의 현재 상태를 조회해요   |
| [`requestPermission`](/documentation/sdk/domains-api/permissions/requestpermission.md)       | 권한을 요청하고 결과를 반환해요 |
| [`openPermissionDialog`](/documentation/sdk/domains-api/permissions/openpermissiondialog.md) | 권한 설정 다이얼로그를 띄워요  |

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

### withPermission

#### 기능 설명

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

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

#### 타입

**Params**

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

**Response**

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

#### 에러

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

#### 예시 코드

```js
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**

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

**Response**

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

#### 예시 코드

```js
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`를 상속해요.

#### 타입

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

#### 예시 코드

```js
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`를 상속해요.

#### 타입

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

#### 예시 코드

```js
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`를 상속해요.

#### 타입

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

#### 예시 코드

```js
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`를 상속해요.

#### 타입

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

#### 예시 코드

```js
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`를 상속해요.

#### 타입

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

#### 예시 코드

```js
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`예요.

#### 타입

```ts
const StartUpdateLocationPermissionError = GetCurrentLocationPermissionError;
```

#### 예시 코드

```js
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`를 상속해요.

#### 타입

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

#### 예시 코드

```js
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

#### 기능 설명

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

#### 타입

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

### PermissionAccess

#### 기능 설명

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

#### 타입

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

### PermissionStatus

#### 기능 설명

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

#### 타입

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

### PermissionFunctionName

#### 기능 설명

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

#### 타입

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

### PermissionErrorConstructorParams

#### 기능 설명

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

#### 타입

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

### PermissionErrorType

#### 기능 설명

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

#### 타입

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

### GetPermissionFunction

#### 기능 설명

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

#### 타입

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

### PermissionDialogFunction

#### 기능 설명

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

#### 타입

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

### PermissionFunctionWithDialog

#### 기능 설명

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

#### 타입

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/permissions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.