# packlets.js, packlets.css, session token

Everything for your app's page: the bridge, the stylesheet and the token.

Reference for the page of your [app](https://packlets.app/en/docs/apps.md): the `packlets.js` bridge, the session token, and the `packlets.css` stylesheet.

## packlets.js

```html
<script src="https://packlets.app/embed/packlets.js"></script>
```

After that, the `packlets` object is available:

| Call | Result |
|---|---|
| `packlets.inPacklets` | `true` if the page runs in the Packlets app, otherwise `false`. Not a call, but a value. |
| `packlets.launch` | [Launch data](#launch-data), available immediately on load: `{ v, packlet_id, platform, theme, locale }`. Not a call, but a value. |
| `packlets.locale` | Language of the app: `"de"` or `"en"` (see [Language](#language)). Not a call, but a value. |
| `packlets.theme` | The colors of Packlets (see [Colors](#colors)). Not a call, but a value. |
| `packlets.ready()` | Reports that the page is ready. Packlets then hides the placeholder. Only needed with `data-ready="manual"`. |
| `await packlets.token()` | The [session token](#session-token) as text. Right after loading, it comes from the launch data without any wait. |
| `await packlets.fetch(url, init)` | Like `fetch()`, but sets `Authorization: Bearer <token>` with a fresh token. Returns the normal response. |
| `await packlets.info()` | `{ app: "packlets", version: 2, packlet_id: "…", platform: "iOS", theme: {…}, locale: "en" }`. `platform` is `iOS` or `android`, `locale` is `de` or `en`. |
| `packlets.toast("Saved")` | Short message in the app. The text is cut off after 140 characters. |
| `packlets.open("https://…")` | Opens the address in the phone's browser. `http(s)` only. |
| `packlets.haptic("success")` | Vibration: `tap` (default), `selection`, `success`, or `error`. |
| `await packlets.storage.get(key)` | Stored text or `null`. See [Storage](#storage). |
| `await packlets.storage.set(key, text)` | Stores text (up to 16 KB). |
| `await packlets.storage.remove(key)` | Deletes an entry. |
| `await packlets.storage.keys()` | All keys of this app. |

All calls except the values (`packlets.inPacklets`, `packlets.launch`, `packlets.locale`, `packlets.theme`) return a promise.

- **Outside Packlets** (for example in a browser), the calls fail immediately. So check `packlets.inPacklets` first.
- **Timeout:** If the app doesn't respond within 15 seconds, the call fails.
- **Your address only:** Only pages with the same origin (`https`, host, and port) as the address you set as `page` get responses.
- **Main page only:** Every call carries a secret bridge key from the [launch data](#launch-data). Calls from iframes of other addresses don't have it, and Packlets ignores them. More under [iframes and external content](https://packlets.app/en/docs/apps.md#5-iframes-and-third-party-content).
- When the page runs in Packlets, `<html>` has the class `in-packlets`. Once the script has loaded, the `packlets:ready` event fires on `window`.
- **Reopened:** Packlets keeps the most recently opened pages in memory (up to four). When someone comes back, the page doesn't reload. Instead, the `packlets:activated` event fires on `window`. That is the right moment to refresh stale data. The button at the top right next to the bell reloads the page completely if needed.

### Loading and placeholder

Until your page is ready, Packlets shows the avatar and name of the app. Normally the placeholder disappears as soon as the page has loaded. If your page still loads data afterwards, include the script with `data-ready="manual"` and call `packlets.ready()` yourself when everything is in place. If no `ready()` arrives after six seconds, Packlets hides the placeholder anyway.

```html
<script src="https://packlets.app/embed/packlets.js" data-ready="manual"></script>
<script>
  loadEverything().then(() => packlets.ready());
</script>
```

### Launch data

When loading, Packlets appends launch data to the address, after `#packlets=` (Base64url-encoded JSON). The part after `#` never goes to your server. `packlets.js` reads it immediately, exposes it as `packlets.launch`, and removes it from the address again. For the first 45 seconds, `packlets.token()` returns the session token from the launch data without a detour through the app. That way, your page knows who is opening it on the very first call to your server (like `initData` in Telegram).

`packlets.js` stores the bridge key from the launch data in the `sessionStorage` of your address. That way, `packlets` also works on other pages you link to within your address. You don't have to do anything for this.

### Language

Packlets is available in German and English, depending on the phone's language. This language is in the launch data as `locale` (`"de"` or `"en"`), in `packlets.info()`, and as `packlets.locale`. Outside Packlets, `packlets.locale` uses the browser's language: `de` for German, otherwise `en`. If `<html>` has no `lang` yet, `packlets.js` sets it to this value.

```js
const text = packlets.locale === "de" ? { save: "Speichern" } : { save: "Save" };
document.querySelector("#save").textContent = text.save;
const date = new Intl.DateTimeFormat(packlets.locale, { dateStyle: "medium" }).format(new Date());
```

If your server builds texts itself, the `Accept-Language` header helps: Packlets sends it when loading the page, in the language of the app.

### Colors

`packlets.theme` contains the colors of Packlets: `bg`, `surface`, `text`, `text_secondary`, `text_tertiary`, `field`, `cta`, `on_cta`, `danger`, and `scheme` (`light`). `packlets.js` also sets them as CSS variables on `<html>`, for example `--packlets-bg`, `--packlets-text`, `--packlets-cta`, or `--packlets-text-secondary`. That way, your page fits the app without any colors of its own.

### Spacing

In Packlets, your page fills the whole area below Packlets' slim header down to the bottom edge (full screen). The header always stays the same and covers nothing. At the bottom, Packlets sets the CSS variable `--packlets-inset-bottom` (the iPhone's home bar) and gives `<html>` this spacing as padding; `--packlets-inset-top` still exists but is `0`. Normally you don't have to do anything.

- If you want to fill the full height without scrolling, subtract the insets: `min-height: calc(100vh - var(--packlets-inset-top) - var(--packlets-inset-bottom))`.
- If you want to handle everything yourself, write `<html data-packlets-insets="manual">` and use the variables where appropriate.

### Storage

`packlets.storage` stores small texts on the device, separated by account and app. If two accounts share a phone, neither sees the other's entries. That sets it apart from the page's normal `localStorage`. Up to 100 entries per app, each up to 16 KB. For objects, use `JSON.stringify` and `JSON.parse`. When someone signs out, the entries stay on the device. If they delete their account, the entries are worthless, because nobody else can read them.

## Session token

A JWT that says who is currently opening the page in Packlets.

| | |
|---|---|
| Algorithm | `HS256` |
| Secret | SHA-256 hash of your key as lowercase hex text. The same as for the [webhook signature](https://packlets.app/en/docs/ereignisse.md#signature). |
| Validity | 60 seconds |

| Field | Content |
|---|---|
| `iss` | `https://api.packlets.app` |
| `aud` | ID of your packlet. The same as `packlet_id` in every webhook event. |
| `sub` | ID of the user in Packlets. Always stays the same for the same user. |
| `email` | The user's email address. |
| `name` | The user's name, may be missing. |
| `iat`, `exp` | Issued at and valid until, as Unix time. |
| `jti` | Unique identifier of this token. |

On your server, always check three things: the signature, `exp`, and that `aud` is your packlet. If you generate a new key in the app, all tokens become invalid immediately.

## Let Packlets verify the token

Without a JWT library of your own, your server asks Packlets. This call needs no key.

```http
POST https://api.packlets.app/v1/session-token/verify
Content-Type: application/json
```

| Field | Type | Required | Meaning |
|---|---|---|---|
| `token` | text | yes | The token from the `Authorization` header of the request to your server. |

Response for a valid token:

```json
{
  "valid": true,
  "packlet_id": "9d2f7c10-3a5b-4c8e-9f21-6b7d8e9f0a12",
  "page_url": "https://your-site.example/app",
  "user": { "id": "4f1c…", "email": "you@example.com", "name": "You" },
  "expires_at": "2026-11-10T08:16:00.000Z"
}
```

Otherwise status `401`:

```json
{ "valid": false, "error": "invalid_token", "message": "The token is invalid or has expired." }
```

> **Careful:** Compare `packlet_id` with the ID of your packlet. Otherwise your server also accepts tokens that were issued for someone else's packlet. If your server serves many packlets (for example one app for all users), check `page_url` instead: that is the page the packlet is currently showing.

The [rate limit](https://packlets.app/en/docs/api.md#rate-limit) applies to this call, counted per address of your server.

## packlets.css

```html
<link rel="stylesheet" href="https://packlets.app/embed/packlets.css">
```

The stylesheet brings the Lato font, the app's colors, and these building blocks:

| Class | Used for |
|---|---|
| `packlets` | Frame of the page: 16 pixels of padding, blocks stacked with 12 pixels of spacing, at least as tall as the screen. |
| `packlets-title`, `packlets-big` | Heading (20 px) and large number (44 px). |
| `packlets-sub`, `packlets-label`, `packlets-note` | Gray secondary text, section label in capitals, small note. |
| `packlets-row`, `packlets-spread`, `packlets-grow`, `packlets-push` | Side by side; spread to the edges; fill space; push to the bottom. |
| `packlets-button` | Button like in the app, 44 px tall. Plus `is-secondary` (light) and `is-small` (32 px). |
| `packlets-tabs` | Switcher between views. The active tab carries `aria-selected="true"`. |
| `packlets-list` | List with fine divider lines, rows at least 44 px tall. |
| `packlets-table` | Table. Number columns right-aligned with `is-num`. |
| `packlets-field` | Input field. |
| `packlets-chip`, `packlets-dot` | Small badge; status dot green, red with `is-warn`. |
| `packlets-bars` | Small bar chart made of `<i style="height: 40%">`. The active bar carries `is-active`. |

Colors and sizes as variables:

| Variable | Meaning |
|---|---|
| `--packlets-bg` | Background |
| `--packlets-text`, `--packlets-text-2`, `--packlets-text-3` | Main text, secondary text, even lighter text |
| `--packlets-icon` | Icons |
| `--packlets-cta`, `--packlets-on-cta` | Dark blue of the buttons and the text on them |
| `--packlets-field` | Light gray for fields and light buttons |
| `--packlets-selected`, `--packlets-bar` | Selected tab, bars in the chart |
| `--packlets-divider` | Divider lines |
| `--packlets-ok`, `--packlets-warn` | Green and red for status |
| `--packlets-radius` | Corner radius |

Text can't be selected on the page (`user-select: none`), like in an app. A finished example page is at [/embed/beispiel.html](https://packlets.app/embed/beispiel.html).
