# Phone

> Phone notifications, calendar events, compass heading, and phone battery.

Source: https://docs.glassly.ai/app-devs/core-concepts/phone/

`session.phone` reports state from the user's phone: notifications as they post,
calendar events, the phone's compass heading, and the phone's own battery. Each
concern is its own sub-module.
Register a handler and the events start arriving.

```typescript src/background/index.ts
session.phone.notifications.on((data) => {
  session.display.render([{type: "text", id: "msg", box: {x: 0, y: 0, w: 576, h: 288}, text: `${data.app}: ${data.title}`}]);
});
```

Reading notifications needs the `READ_NOTIFICATIONS` permission, posting them
needs `POST_NOTIFICATIONS`, calendar events need
`CALENDAR`, and the phone heading needs `LOCATION`, all declared in your
[manifest](https://docs.glassly.ai/app-devs/core-concepts/miniapp-manifest.md). Phone battery needs no
permission.

## Notifications

`session.phone.notifications.on()` fires when a notification posts on the phone,
or when a miniapp posts one (see [Posting notifications](#posting-notifications)).

```typescript
session.phone.notifications.on((data) => {
  // data: PhoneNotificationData
});
```

Each event is a `PhoneNotificationData`:

| Field | Type | Notes |
|---|---|---|
| `notificationId` | `string` | Stable id from the phone's notification listener. |
| `app` | `string` | Human app name (e.g. `"Messages"`). |
| `title` | `string` | The notification title. |
| `content` | `string` | The notification body. |
| `priority` | `string` | Android priority string; empty on iOS. |
| `timestamp` | `number` | Unix ms timestamp. |
| `packageName` | `string` | Reverse-DNS package/bundle id of the originating app. For a miniapp's notification, the miniapp's package name. |
| `system` | `boolean` | `true` for the phone's own notifications, `false` for one a miniapp posted. |
| `source` | `string?` | The posting miniapp's package name. Absent when `system` is `true`. |

### Dismissals

`session.phone.notifications.onDismissed()` fires when the user swipes away or
clears a notification, and when a miniapp dismisses one it posted.

```typescript
session.phone.notifications.onDismissed((data) => {
  // data: NotificationDismissedData
});
```

Each event is a `NotificationDismissedData`:

| Field | Type | Notes |
|---|---|---|
| `notificationId` | `string` | Same id as the matching post event from `notifications.on(...)`. |
| `notificationKey` | `string?` | Android NotificationKey. More stable than `notificationId` across reposts. |
| `packageName` | `string?` | Reverse-DNS package/bundle id of the originating app. |
| `timestamp` | `number` | Unix ms timestamp of the dismissal. |
| `system` | `boolean` | `false` when the posting miniapp dismissed it. |
| `source` | `string?` | The posting miniapp's package name. Absent when `system` is `true`. |

Phone dismissals are **Android only**. iOS does not expose dismiss callbacks to
apps (an Apple privacy restriction), so on iOS only miniapp dismissals arrive.
The matching `notifications.on()` post-event works on both platforms.

### Posting notifications

`session.phone.notifications.post()` sends a notification down the same path the
phone's own notifications take. The dashboard shows it in its viewer and pops
it up like any other, every miniapp reading notifications receives it with
`system: false` and `source` set to your package, and on glasses without the
dashboard view it reaches the wearer the way a phone notification would (the
glasses' own notification centre where the phone uploads to it, or the host's
card and speech). Declare `POST_NOTIFICATIONS`.

```typescript
const id = await session.phone.notifications.post({
  title: "Pasta timer",
  content: "Drain it now",
  id: "pasta", // optional: posting again with the same id replaces it
});

await session.phone.notifications.dismiss(id);
```

| Option | Type | Notes |
|---|---|---|
| `title` | `string?` | Cut at 200 characters. |
| `content` | `string?` | Cut at 2,000 characters. A notification needs a title or content. |
| `id` | `string?` | Your key for the notification; one is generated when omitted. |

`post()` resolves with the id. Readers see `notificationId` as
`<your package>:<id>`, so ids never collide with another miniapp's. The
notification carries your miniapp's name as `app`, and the wearer's per-app
notification filter lists your miniapp and can block it. Nothing is posted to
the phone's own notification shade.

## Calendar

`session.phone.calendar.listEvents()` reads a current snapshot from all event
calendars on the phone. Declare `CALENDAR` as a required permission; the Glassly
App requests access before opening the miniapp.

```typescript
const result = await session.phone.calendar.listEvents({
  startsAt: new Date(),
  endsAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
  limit: 50,
});
```

The date window may span at most 31 days. `limit` defaults to 50 and may not
exceed 100. The result contains `events` and a `truncated` flag. Each event has:

| Field | Type | Notes |
|---|---|---|
| `id` | `string` | Unique occurrence id, including recurring instances. |
| `calendarId` | `string` | Id of the source calendar. |
| `title` | `string` | The event title. |
| `startsAt` | `string` | ISO 8601 start time. All-day events preserve their calendar timezone offset. |
| `endsAt` | `string` | ISO 8601 end time. All-day events preserve their calendar timezone offset. |
| `timezone` | `string?` | The event's timezone. |
| `allDay` | `boolean` | Whether it's an all-day event. |
| `location` | `string?` | The event location. |
| `notes` | `string?` | The event notes. |
| `url` | `string?` | The platform calendar URL field, when available. |
| `links` | `string[]` | Deduplicated HTTPS links found in URL, location, and notes. |

## Phone heading

`session.phone.heading.onUpdate()` streams the phone's compass heading on both
Android and iOS. The phone compass starts on the first subscriber and stops on
the last. For the heading of the glasses themselves, use
[`session.compass`](https://docs.glassly.ai/app-devs/core-concepts/imu.md#compass).

```typescript
const off = session.phone.heading.onUpdate((data) => {
  // data.degrees: 0 = north, 90 = east
});
```

Each event is a `HeadingData`:

| Field | Type | Notes |
|---|---|---|
| `degrees` | `number` | Phone compass heading in degrees. `0` = north, `90` = east. |

`session.phone.heading.hasPermission` is `true` when `LOCATION` is declared in
your manifest, the same key [`session.location`](https://docs.glassly.ai/app-devs/core-concepts/location.md)
uses. It reports the declaration, not the OS grant.

## Phone battery

`session.phone.onBattery()` reports the phone's battery. It stays flat (not
sub-namespaced) because it's a single event.

```typescript
session.phone.onBattery((data) => {
  // data: BatteryData
});
```

Each event is a `BatteryData`:

| Field | Type | Notes |
|---|---|---|
| `level` | `number` | Battery level. |
| `charging` | `boolean` | Whether the phone is charging. |

## Cleaning up

Every subscription returns an unsubscribe function. The `notifications`
sub-module also has a `stop()` that tears down every notification subscription
at once. Calendar snapshots do not create a subscription.

```typescript
const off = session.phone.notifications.on(handler);
off();                              // drop this one

session.phone.notifications.stop(); // drop all notification subscriptions
```

`session.phone.notifications.hasPermission` tells you whether `READ_NOTIFICATIONS`
is declared in your manifest, and `session.phone.calendar.hasPermission` tells you
whether `CALENDAR` is declared. Neither tells you whether the user granted the OS
prompt. A calendar request rejects with `PERMISSION_DENIED` if access was later
revoked. See
[Permissions](https://docs.glassly.ai/app-devs/core-concepts/permissions.md).
