# routes

## Type Aliases

### DiscoverSearchHandoff

```ts
type DiscoverSearchHandoff = object;
```

Optional post-search filter/sort applied after a Discover catalog query.

#### Properties

##### authors?

```ts
authors?: string[];
```

Seed include filters (server-applied).

##### excludeSources?

```ts
excludeSources?: string[];
```

##### field?

```ts
field?: "author" | "narrator" | "series" | "genre";
```

Storefront-scoped search (`author` / `narrator` / `series` / `genre`).

##### ~~filterKind?~~

```ts
filterKind?: "all" | "authors" | "series" | "narrators" | "genres" | "sources";
```

###### Deprecated

legacy single-dimension filter

##### ~~filterValue?~~

```ts
filterValue?: string;
```

###### Deprecated

##### genres?

```ts
genres?: string[];
```

##### hideVirtualVoice?

```ts
hideVirtualVoice?: boolean;
```

When false, do not exclude Virtual Voice (default hide is on).

##### language?

```ts
language?: string;
```

Hard language include (`en`, `zh`, …) or `__all__` for no hard filter.
Omit to use the browser language default.

##### minRating?

```ts
minRating?: number;
```

##### narrators?

```ts
narrators?: string[];
```

##### q

```ts
q: string;
```

##### runtimeBucket?

```ts
runtimeBucket?: "any" | "under6" | "6to12" | "12to20" | "over20";
```

##### series?

```ts
series?: string[];
```

##### sort?

```ts
sort?: 
  | "relevance"
  | "popularity"
  | "rating"
  | "title"
  | "author"
  | "price"
  | "length";
```

##### sortDir?

```ts
sortDir?: "asc" | "desc";
```

##### ~~sortKey?~~

```ts
sortKey?: 
  | "title"
  | "author"
  | "series"
  | "relevance"
  | "popularity"
  | "rating"
  | "price"
  | "length";
```

###### Deprecated

##### sources?

```ts
sources?: string[];
```

***

### JoinPage

```ts
type JoinPage = 
  | "approve"
  | "clerk-approve"
  | "callback"
  | "clerk-callback"
  | "player-approve";
```

A page that sign-in flows from other installs own: a branch's consent
(`approve`), a clerk's consent (`clerk-approve`), the joining install's
callback (`callback`), this install's library card callback
(`clerk-callback`), or a player app's consent (`player-approve`).

## Variables

### CLERK\_APPROVE\_PATH

```ts
const CLERK_APPROVE_PATH: "/clerk/approve" = "/clerk/approve";
```

The library's consent page for a clerk's sign-in (a library card).

***

### CLERK\_CALLBACK\_PATH

```ts
const CLERK_CALLBACK_PATH: "/clerk/callback" = "/clerk/callback";
```

Where a library sends the browser back after a library card sign-in.

***

### JOIN\_APPROVE\_PATH

```ts
const JOIN_APPROVE_PATH: "/join/approve" = "/join/approve";
```

The library's consent page for a branch's sign-in.

***

### JOIN\_CALLBACK\_PATH

```ts
const JOIN_CALLBACK_PATH: "/join/callback" = "/join/callback";
```

Where a library sends the joining install's browser back.

***

### PLAYER\_APPROVE\_PATH

```ts
const PLAYER_APPROVE_PATH: "/apps/approve" = "/apps/approve";
```

The library's consent page for a player app's browser sign-in.

## Functions

### dropTicketUnlessInvitePath()

```ts
function dropTicketUnlessInvitePath(): void;
```

Invite magic links are `/invite?ticket=` only. Drop `ticket` on any other
path so `/discover?ticket=` cannot open the accept-invite form.

#### Returns

`void`

***

### isAppPath()

```ts
function isAppPath(pathname): boolean;
```

Returns whether `pathname` is a known GUI route (not an API/static/unknown URL).

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `pathname` | `string` | Document pathname (may include a trailing slash). |

#### Returns

`boolean`

True when the path is owned by the React SPA.

***

### isConsentPage()

```ts
function isConsentPage(page): boolean;
```

True for a consent page, which keeps its address across a sign-in.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `page` | [`JoinPage`](#joinpage) \| `null` | The page, from [joinPage](#joinpage-1). |

#### Returns

`boolean`

Whether it is a branch's, a clerk's or a player app's consent page.

***

### isInvitePath()

```ts
function isInvitePath(pathname?): boolean;
```

True when this document is the magic-link invite route.

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `pathname?` | `string` | `window.location.pathname` | Document pathname. |

#### Returns

`boolean`

True for `/invite` (trailing slash ignored).

***

### joinPage()

```ts
function joinPage(pathname?): JoinPage | null;
```

Which Join a library page this document is, if any.

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `pathname?` | `string` | `window.location.pathname` | Document pathname. |

#### Returns

[`JoinPage`](#joinpage) \| `null`

`approve`, `clerk-approve`, `callback`, `clerk-callback`,
  `player-approve`, or `null`.

***

### normalizeAppView()

```ts
function normalizeAppView(v): AppView;
```

Coerces an unknown string into a valid [AppView](/docs/contributing/ui/api/index.md#appview).

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `v` | `string` \| `undefined` | Candidate view id from the session or URL. |

#### Returns

[`AppView`](/docs/contributing/ui/api/index.md#appview)

Valid view, defaulting to `discover`.

***

### normalizePathname()

```ts
function normalizePathname(pathname): string;
```

Strips a trailing slash (except for `/`).

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `pathname` | `string` | Raw document pathname. |

#### Returns

`string`

Normalized pathname.

***

### pathForView()

```ts
function pathForView(view): string;
```

Returns the canonical document path for an app view.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `view` | [`AppView`](/docs/contributing/ui/api/index.md#appview) | SPA view id. |

#### Returns

`string`

Path such as `/library`.

***

### queueDiscoverSearch()

```ts
function queueDiscoverSearch(handoff): void;
```

Queues a Discover catalog search for the next Discover page mount (cross-view).

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `handoff` | `string` \| [`DiscoverSearchHandoff`](#discoversearchhandoff) | Query string or full handoff object (ignored when `q` is under 2 chars). |

#### Returns

`void`

***

### resolveView()

```ts
function resolveView(pathname, defaultView): AppView;
```

Resolves the view to show for the current URL plus signed-in default.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `pathname` | `string` | Document pathname. |
| `defaultView` | `string` \| `undefined` | Session default view when the path is `/`. |

#### Returns

[`AppView`](/docs/contributing/ui/api/index.md#appview)

Effective [AppView](/docs/contributing/ui/api/index.md#appview).

***

### syncUrlToView()

```ts
function syncUrlToView(view, mode?): void;
```

Updates the URL bar without a full reload.

Drops `ticket` and `sso_error` so a claimed invite URL is not kept on
`/discover?ticket=…` (a refresh of that path would skip the 410 invite page).

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `view` | [`AppView`](/docs/contributing/ui/api/index.md#appview) | `undefined` | View to reflect in the path. |
| `mode?` | `"replace"` \| `"push"` | `"push"` | History `push` (default) or `replace`. |

#### Returns

`void`

***

### takeQueuedDiscoverSearch()

```ts
function takeQueuedDiscoverSearch(): DiscoverSearchHandoff | null;
```

Consumes a queued Discover search (once).

#### Returns

[`DiscoverSearchHandoff`](#discoversearchhandoff) \| `null`

Handoff payload, or `null` when none / invalid.

***

### viewFromPath()

```ts
function viewFromPath(pathname): AppView | null;
```

Maps a document path to an app view, or `null` for `/` (use default_view).

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `pathname` | `string` | Document pathname. |

#### Returns

[`AppView`](/docs/contributing/ui/api/index.md#appview) \| `null`

Matching [AppView](/docs/contributing/ui/api/index.md#appview), or `null` when the path is `/` or unknown.
