# V3 Deep Links

This file is the deployment contract for V3 links emitted by V1 messaging
channels and handled by the V1 mobile companion.

Outbound Telegram, WhatsApp, push, email, and SMS messages must use the
canonical HTTPS form so links survive app-install state, link previews,
forwarding, and desktop-to-mobile handoff. The custom scheme is the installed
app target that the mobile client maps to after the OS resolves the universal
link or app link.

Host and scheme:

- Canonical HTTPS origin: `https://app.oshun.com`
- Custom scheme authority: `oshun://v3`
- Universal/app-link path family: `/v3` and `/v3/*`
- Outbound source attribution: append `?source=<channel>` where channel is one
  of `telegram`, `whatsapp`, `push`, `email`, or `sms`.

## Route Templates

| Surface                         | Canonical HTTPS URL                                            | Custom-Scheme URL                                | Required Parameters |
| ------------------------------- | -------------------------------------------------------------- | ------------------------------------------------ | ------------------- |
| V3 companion home               | `https://app.oshun.com/v3`                                     | `oshun://v3`                                     | none                |
| Tara bookings                   | `https://app.oshun.com/v3/tara/bookings`                       | `oshun://v3/tara/bookings`                       | none                |
| Tara booking detail             | `https://app.oshun.com/v3/tara/bookings/{bookingId}`           | `oshun://v3/tara/bookings/{bookingId}`           | `bookingId`         |
| Arete continuations             | `https://app.oshun.com/v3/arete/continuation`                  | `oshun://v3/arete/continuation`                  | none                |
| Arete continuation detail       | `https://app.oshun.com/v3/arete/continuation/{continuationId}` | `oshun://v3/arete/continuation/{continuationId}` | `continuationId`    |
| Ticket inventory                | `https://app.oshun.com/v3/tickets`                             | `oshun://v3/tickets`                             | none                |
| Ticket detail                   | `https://app.oshun.com/v3/tickets/{ticketId}`                  | `oshun://v3/tickets/{ticketId}`                  | `ticketId`          |
| Follow list                     | `https://app.oshun.com/v3/follows`                             | `oshun://v3/follows`                             | none                |
| Follow detail                   | `https://app.oshun.com/v3/follows/{followId}`                  | `oshun://v3/follows/{followId}`                  | `followId`          |
| Saraswati signed-edition wallet | `https://app.oshun.com/v3/saraswati/wallet`                    | `oshun://v3/saraswati/wallet`                    | none                |
| Saraswati signed-edition detail | `https://app.oshun.com/v3/saraswati/wallet/{editionId}`        | `oshun://v3/saraswati/wallet/{editionId}`        | `editionId`         |

## Channel Helpers

Use `@oshun/messaging-channels` for outbound V3 links:

```ts
import { buildV3MessagingSharePayload } from '@oshun/messaging-channels';

const share = buildV3MessagingSharePayload({
  channel: 'telegram',
  link: {
    surface: 'tara-booking',
    bookingId: 'booking-tara-sunrise-2026-05-20',
  },
});
```

The `share.url` value is the URL to send in the channel body or button:

```text
https://app.oshun.com/v3/tara/bookings/booking-tara-sunrise-2026-05-20?source=telegram
```

The payload also carries `canonicalHttpsUrl` without source attribution and
`customSchemeUrl` for native QA, app-store review scripts, and mobile route
contract tests. Do not send `oshun://...` links directly through Telegram,
WhatsApp, push, email, or SMS.

## Launch Behavior

1. A user taps the canonical HTTPS URL.
2. iOS Universal Links or Android App Links open the V1 mobile companion when
   installed and verified for `app.oshun.com`.
3. The V1 mobile companion resolves the `/v3/*` path into the matching V3
   surface and asks the authenticated launch router for the UE5 Lilith target.
4. If the UE5 native client is installed, the companion opens the native launch
   deep link.
5. If the UE5 native client is not installed, the companion opens the original
   canonical HTTPS route in the V1 web fallback with the bearer session carried
   only in the URL fragment.