platforms

The deep-link table (services/redirect/src/platforms.ts) is the core of Zippy. Each platform is one data object; from it Zippy derives the iOS, Android, and web link forms uniformly. Zippy ships with these 22:

† Schemeless (Android-only native open). GitHub, Play Store, and Snapchat register no custom URL scheme — their apps are reachable only via https App Links (Android) and Universal Links (iOS). So their "scheme" is https and Zippy hands the app the genuine URL: Android gets a real native-open; iOS lands on the web page (Universal Links don't fire inside in-app webviews — the exact gap Zippy exists to close). See the GitHub / Snapchat note below.

‡ App Store is iOS-native by design. itms-apps is a built-in iOS system scheme, so apps.apple.com links open the App Store app straight from a webview. There is no Apple store on Android, so those links correctly serve web there (the package shown is inert on the Apple host). Google Play is the separate play-store row, which opens the Play Store app on Android.

Host matching strips a leading www. and is case-insensitive. A destination whose host no platform owns is never matched — it simply 301s.

What each URL shape opens

Add a platform (PR guide)

Adding a platform is a small, self-contained PR against services/redirect. You touch two files: the table and its test.

1. Add one object to PLATFORMS

In services/redirect/src/platforms.ts, append a Platform:

type Platform = {
  key: string; // stable id, also the `deeplink` value in API responses
  scheme: string; // the app's custom URL scheme, e.g. "spotify"
  androidPackage: string; // Play Store package id, e.g. "com.spotify.music"
  hosts: string[]; // lowercased hostnames it owns, no leading "www."
  path: (url: URL) => string; // scheme-specific suffix after "scheme://", or "" for app home
};

Example:

{
  key: "spotify",
  scheme: "spotify",
  androidPackage: "com.spotify.music",
  hosts: ["open.spotify.com"],
  path: (url) => {
    const s = url.pathname.split("/").filter(Boolean);
    // /track/<id> → spotify:track:<id>-style suffix the app understands, else app home
    if ((s[0] === "track" || s[0] === "album" || s[0] === "playlist") && s[1]) {
      return `${s[0]}/${s[1]}`;
    }
    return "";
  },
}

Zippy derives the iOS (scheme://path), Android (intent://…), and web-fallback forms from these fields — nothing else in the Worker changes.

2. Add test rows to test/platforms.test.ts

Cover each URL shape your path handles (profile, content, and the app-home fallback), and run the suite:

bun --filter @zippy/redirect test

Tips

• Verify the scheme on a real device if you can — schemes are undocumented and drift. If you're unsure, leave a // ponytail:-style note; the web fallback keeps a wrong scheme safe.
• Return "" rather than guessing when a content type has no dependable scheme. An app-home open plus the web fallback beats a broken deep link.
• Keep hosts lowercase and without www. — matching normalizes the request host the same way.