roblox-deeplink-parser 0.1.20

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: [RoSeal-Extension]

package/.github/workflows/publish.yaml

@@ -0,0 +1,29 @@
+name: Publish on JSR/
+
+on:
+  push:
+    branches: [main]
+  release:
+    types: [created]
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Setup Repo
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish on JSR
+        if: github.event_name == 'release' && github.repository == 'RoSeal-Extension/Roblox-DeepLink-Parser'
+        run: bunx jsr publish --allow-slow-types --allow-dirty

package/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+    "editor.defaultFormatter": "biomejs.biome",
+    "editor.formatOnSave": true,
+	"editor.codeActionsOnSave": {
+		"source.organizeImports": "explicit",
+		"source.fixAll": "explicit"
+	},
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Julli4n
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# Roblox DeepLink Parser
+Parse Roblox deeplinks (roblox://*), website links (www.roblox.com), and appsflyer links (ro.blox.com) to get params and get new appysflyer/deeplink/website URLs.
+
+## Example
+```ts
+import DeepLinkParser from "@roseal/roblox-deeplink-parser";
+const parser = new DeepLinkParser();
+
+// same as parser.parseWebsiteLink
+parser.parseLink("https://www.roblox.com/my/avatar").then((link) => {
+	if (link) {
+        // roblox://navigation/avatar
+		console.log(link.toProtocolUrl());
+        // https://www.roblox.com/my/avatar
+		console.log(link.toWebsiteUrl());
+        // https://ro.blox.com/Ebh5?af_dp=roblox%3A%2F%2Fnavigation%2Favatar&af_web_dp=https%3A%2F%2Fwww.roblox.com%2Fmy%2Favatar
+		console.log(link.toAppsFlyerUrl());
+	}
+});
+
+// ... and you can do these as well specifically:
+parser.parseProtocolLink("roblox://navigation/avatar")
+parser.parseAppsFlyerLink("https://ro.blox.com/Ebh5?af_dp=roblox%3A%2F%2Fnavigation%2Favatar&af_web_dp=https%3A%2F%2Fwww.roblox.com%2Fmy%2Favatar");
+parser.parseWebsiteLink("https://www.roblox.com/my/avatar");
+```
+
+## Reference
+| Deeplink | Website Equivalent | Description |
+| -------- | ------------------ | ----------- |
+| `roblox://experiences/start` or `roblox://` <br />Search Parameters:<br />- placeId<br />- userId<br />- gameInstanceId<br /> - accessCode<br />- linkCode<br />- launchData<br /> - joinAttemptId<br />- joinAttemptOrigin<br />- reservedServerAccessCode<br />- callId<br />- browserTrackerId<br />- referralPage<br />- referredByPlayerId<br />- eventId<br />- isoContext | `www.roblox.com/games/start` <br />Search Parameters:<br />- placeId<br /> - gameInstanceId<br /> - accessCode<br />- linkCode<br />- launchData<br /> - joinAttemptId<br />- joinAttemptOrigin<br />- reservedServerAccessCode<br />- callId<br />- browserTrackerId<br />- referralPage<br />- referredByPlayerId | Join a server or user, for more information please see [Bloxstrap wiki](https://github.com/bloxstraplabs/bloxstrap/wiki/A-deep-dive-on-how-the-Roblox-bootstrapper-works#starting-roblox)
+| `roblox://navigation/profile` <br />Search Parameters:<br />- groupId<br />- userId<br />- friendshipSourceType | `www.roblox.com/users/{userId}/profile` or `www.roblox.com/communities/{groupId}/name` | Open webview of a user or community on the website
+| `roblox://navigation/group` <br />Search Parameters:<br />- groupId<br />- forumCategoryId<br />- forumPostId<br />- forumCommentId| `www.roblox.com/communities/{groupId}/name` | Open webview of a community page
+| `roblox://navigation/profile_card` <br />Search Parameters:<br />- userId | `www.roblox.com/users/{userId}/profile` | Opens the native app view of a user profile
+| `roblox://navigation/content_posts` <br />Search Parameters:<br />- userId<br />- postId | N/A | Show content posts "captures" from a user or a specific post
+| `roblox://navigation/share_links` <br />Search Parameters:<br />- type<br />- code | `www.roblox.com/share-links` <br />Search Parameters:<br />- type<br />- code | Resolve a share link, which could be a friend invite, experience details link, experience invite, etc.
+| `roblox://navigation/gift_cards` | `www.roblox.com/giftcards` | Open webview of the giftcards page
+| `roblox://navigation/external_web_link` <br />Search Parameters:<br />- domain (zendesk)<br />- locale<br />- articleId | `en.help.roblox.com/hc/{locale}/articles/{articleId}` | Open webview of a zendesk article
+| `roblox://navigation/chat` <br />Search Parameters:<br />- userId<br />- chatId<br />- entryPoint | N/A | Open chat conversation with a user or another type of conversation (group)
+| `roblox://navigation/appeals` <br />Search Parameters:<br />- vid | `www.roblox.com/report-appeals#/v/{vid}` | Open webview of appeals page or a certain appeal request
+| `roblox://navigation/home` | `www.roblox.com/home` | Open home page
+| `roblox://navigation/event_details` <br />Search Parameters:<br />- eventId | `www.roblox.com/events/{eventId}` | Open details of an experience event
+| `roblox://navigation/crossdevice` <br />Search Parameters:<br />- code | `www.roblox.com/crossdevicelogin/confirmcode` | Open crossdevice login page, and automatically enter the code if there was one in the deeplink
+| `roblox://navigation/contacts` <br />Search Parameters:<br />- contactId<br />- assetId<br />- avatarImageUrl | N/A | Open contacts page (or friend requests page)
+| `roblox://navigation/avatar_clothing_sort` | N/A | Open avatar clothing sorting page
+| `roblox://navigation/avatar_profile_picture_editor` | N/A | Open avatar profile picture editor page
+| `roblox://navigation/catalog` | `www.roblox.com/catalog` | Open avatar marketplace page
+| `roblox://navigation/catalog/equip` <br />Search Parameters:<br />- itemId<br />- itemType (Asset\|Bundle) | N/A | Equip or try on an avatar item
+| `roblox://navigation/friends` | `www.roblox.com/users/friends` | View the currently authenticated user's friends
+| `roblox://navigation/avatar` <br />Search Parameters:<br />- itemType (Character)<br />- itemId | `www.roblox.com/my/avatar` | Open the avatar editor page
+| `roblox://navigation/more` | N/A | Open the More section of the app
+| `roblox://navigation/games` | `www.roblox.com/charts` | Open the charts page
+| `roblox://navigation/sort` <br />Search Parameters:<br />- sortName | `www.roblox.com/charts#/sortName/{sortId}` | Open the charts sort page
+| `roblox://navigation/item_details` <br />Search Parameters:<br />- itemType (Look\|Asset\|Bundle)<br />- itemId | `www.roblox.com/catalog/{itemId}/name`, `www.roblox.com/bundles/{itemId}/name`, or `www.roblox.com/looks/{itemId}/name` | Open the details page of an avatar asset, bundle, or look
+| `roblox://navigation/account_info` | `www.roblox.com/my/account#!/info` | Open webview of the account settings info page
+| `roblox://navigation/notification_settings` | `www.roblox.com/my/account#!/notifications` | Open webview of the account settings notifications page
+| `roblox://navigation/privacy_settings` | `www.roblox.com/my/account#!/privacy` | Open webview of the account settings privacy page
+| `roblox://navigation/parental_controls` | `www.roblox.com/my/account#!/parental-controls` | Open webview of the account settings parental controls page
+| `roblox://navigation/spending_settings` | `www.roblox.com/my/account#!/payment-methods` | Open webview of the account settings payment methods page
+| `roblox://navigation/qr_code_redemption` <br />Search Parameters:<br />- itemType (Asset\|Bundle)<br />- itemId | N/A | Redeem an item which can be obtained by scanning a QR code
+| `roblox://navigation/game_details` <br />Search Parameters:<br />- gameId<br />- privateServerLinkCode | `www.roblox.com/games/{placeId}/name` <br />Search Parameters:<br />- privateServerLinkCode | Opens the details page of an experience
+| `roblox://navigation/security_alert` <br />Search Parameters:<br />- payload | `www.roblox.com/security-feedback` <br />Search Parameters:<br />- payload | Opens security feedback page
+| `roblox://navigation/experience_sort` <br />Search Parameters:<br />- sortId | N/A | Opens an experience sort page on the home page
+| `roblox://navigation/party` | N/A | Opens the party page
+| `roblox://navigation/app_permissions_settings` | `www.roblox.com/my/account#!/app-permissions` | Opens the app permissions page
+| `roblox://navigation/screentime_subsettings` | `www.roblox.com/my/account#!/privacy/Screentime` | Opens the screentime subsettings page
+| `roblox://navigation/blocked_experiences_subsettings` | `www.roblox.com/my/account#!/privacy/ContentRestrictions/BlockedExperiences` | Opens the blocked experiences subsettings page
+| `roblox://navigation/blocked_users_subsettings` | `www.roblox.com/my/account#!/privacy/BlockedUsers` | Opens the blocked users subsettings page
+| `roblox://navigation/experience_chat_subsettings` | `www.roblox.com/my/account#!/privacy/ExperienceChat` | Opens the experience chat subsettings page
+| `roblox://navigation/party_subsettings` | `www.roblox.com/my/account#!/privacy/Party` | Opens the party subsettings page
+| `roblox://navigation/voice_subsettings` | `www.roblox.com/my/account#!/privacy/Voice` | Opens the voice subsettings page
+| `roblox://navigation/trading_inventory_subsettings` | `www.roblox.com/my/account#!/privacy/TradingInventory` | Opens the trading inventory subsettings page
+| `roblox://navigation/friends_contacts_subsettings` | `www.roblox.com/my/account#!/privacy/FriendsAndContacts` | Opens the friends and contacts subsettings page
+| `roblox://navigation/private_server_subsettings` | `www.roblox.com/my/account#!/privacy/PrivateServers` | Opens the private server subsettings page
+| `roblox://navigation/visibility_subsettings` | `www.roblox.com/my/account#!/privacy/Visibility` | Opens the visibility subsettings page
+| `roblox://navigation/fae` | N/A | Opens the facial age estimation page
+| `roblox://navigation/fae_upsell_overlay` | N/A | Opens the facial age estimation overlay page
+| `roblox://navigation/account_recovery` <br />Search Parameters:<br />- origin<br />- username<br />- recoverySessionId | `www.roblox.com/login/forgot-password-or-username` <br />Search Parameters:<br />- origin<br />- username<br />- recoverySessionId | Opens the account recovery page
+| `roblox://navigation/messages` | `https://www.roblox.com/my/messages` | Opens the systen messages page

package/biome.json

@@ -0,0 +1,28 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.4/schema.json",
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+	"files": {
+		"ignoreUnknown": false,
+		"includes": ["**"]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"assist": { "actions": { "source": { "organizeImports": "on" } } },
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	}
+}

package/jsr.json

@@ -0,0 +1,8 @@
+{
+	"name": "@roseal/roblox-deeplink-parser",
+	"version": "0.1.20",
+	"exports": {
+		".": "./src/DeepLinkParser.ts",
+		"./authedProtocol": "./src/AuthedProtocolParser.ts"
+	}
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "roblox-deeplink-parser",
+	"private": false,
+	"version": "0.1.20",
+	"type": "module",
+	"main": "./dist/DeepLinkParser.js",
+	"module": "./dist/DeepLinkParser.js",
+	"types": "./dist/DeepLinkParser.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/DeepLinkParser.js",
+			"types": "./dist/DeepLinkParser.d.ts"
+		},
+		"./authedProtocol": {
+			"import": "./dist/AuthedProtocolParser.js",
+			"types": "./dist/AuthedProtocolParser.d.ts"
+		}
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"typescript": "latest",
+		"@biomejs/biome": "latest"
+	},
+	"scripts": {
+		"build": "bunx bunup src/DeepLinkParser.ts src/AuthedProtocolParser.ts"
+	}
+}

package/src/AuthedProtocolParser.ts

@@ -0,0 +1,292 @@
+import {
+	DEFAULT_PLACELAUNCHER_URL,
+	DEFAULT_ROBLOX_PLAYER_AUTHED_PROTOCOL,
+	DEFAULT_ROBLOX_STUDIO_AUTH_AUTHED_PROTOCOL,
+	DEFAULT_ROBLOX_STUDIO_AUTHED_PROTOCOL,
+} from "./utils/constants";
+
+export type AuthedProtocolUrls<T> = {
+	robloxPlayerProtocol: T;
+	robloxStudioProtocol: T;
+	robloxStudioAuthProtocol: T;
+	placeLauncherUrl: string;
+};
+
+export type AuthedProtocolParserConstructorProps<T extends string> = {
+	urls?: Partial<AuthedProtocolUrls<T>>;
+};
+
+export type AuthedLaunchMode =
+	| "edit"
+	| "plugin"
+	| "play"
+	| "build"
+	| "app"
+	| "asset";
+
+export type AuthLaunchExp = "InApp" | "PreferInApp" | "InBrowser";
+
+export type AuthedStudioTask =
+	| "EditFile"
+	| "EditPlace"
+	| "EditPlaceRevision"
+	| "StartClient"
+	| "StartTeamTest"
+	| "InstallPlugin"
+	| "TryAsset"
+	| "RemoteDebug"
+	| "StartServer";
+
+export type AuthedDistributorType = "Global" | "ChinaJoinVenture";
+
+export type AuthedOtherParams = {
+	browsertrackerid?: number;
+	robloxLocale?: string;
+	gameLocale?: string;
+	channel?: string;
+	LaunchExp?: AuthLaunchExp;
+	avatar?: string;
+	assetid?: number;
+	pluginid?: number;
+	placeid?: number;
+	universeid?: number;
+	script?: string;
+	placelauncherurl?: string;
+	task?: AuthedStudioTask;
+	traceId?: string;
+	userId?: number;
+	browser?: string;
+	distributorType?: AuthedDistributorType;
+	[key: string]: string | number | undefined;
+};
+
+export type BuildAuthedProtocolUrlParameters<T extends string> = {
+	type: T;
+	launchMode?: AuthedLaunchMode;
+	gameInfo?: string;
+	launchTime?: string;
+	baseUrl?: string;
+	otherParams?: AuthedOtherParams;
+
+	// auth params
+	state?: string;
+	code?: string;
+};
+
+export type BuildAuthedPlaceLauncherRequest =
+	| "RequestGame"
+	| "RequestCloudEdit"
+	| "RequestGameJob"
+	| "RequestFollowUser"
+	| "RequestPrivateGame"
+	| "RequestPlayTogetherGame"
+	| "RequestGameApp"
+	| "RequestInvalid"
+	| "RequestPlayWithParty"
+	| "CheckGameJobStatus"
+	| "RequestReservedGame"
+	| "RequestCrossExpVoice";
+
+export type AuthedPrivateGameMode = "ReservedServer";
+
+export type BuildAuthedPlaceLauncherURLParameters<T extends string> = {
+	request: BuildAuthedPlaceLauncherRequest;
+	placeId?: number;
+	jobId?: string;
+	gameId?: string;
+	gender?: string;
+	genderId?: number;
+	accessCode?: string;
+	linkCode?: string;
+	launchData?: string;
+	privateGameMode?: AuthedPrivateGameMode;
+	teleportType?: string;
+	reservedServerAccessCode?: string;
+	referralPage?: string;
+	referredByPlayerId?: number;
+	conversationId?: number;
+	isPartyLeader?: boolean;
+	isTeleport?: boolean;
+	partyGuid?: string;
+	isPlayTogetherGame?: boolean;
+	joinAttemptId?: string;
+	joinAttemptOrigin?: T;
+	callId?: string;
+	browserTrackerId?: number;
+	eventId?: string;
+	isolationContext?: string;
+	gameJoinContext?: string;
+	userId?: number;
+};
+
+export default class AuthedProtocolParser<T extends string, U extends string> {
+	public _urls: AuthedProtocolUrls<T> = {
+		robloxPlayerProtocol: DEFAULT_ROBLOX_PLAYER_AUTHED_PROTOCOL as T,
+		robloxStudioProtocol: DEFAULT_ROBLOX_STUDIO_AUTHED_PROTOCOL as T,
+		robloxStudioAuthProtocol: DEFAULT_ROBLOX_STUDIO_AUTH_AUTHED_PROTOCOL as T,
+		placeLauncherUrl: DEFAULT_PLACELAUNCHER_URL,
+	};
+
+	constructor(props?: AuthedProtocolParserConstructorProps<T>) {
+		if (props?.urls) {
+			if (props.urls.robloxPlayerProtocol) {
+				this._urls.robloxPlayerProtocol = props.urls.robloxPlayerProtocol;
+			}
+			if (props.urls.robloxStudioProtocol) {
+				this._urls.robloxStudioProtocol = props.urls.robloxStudioProtocol;
+			}
+			if (props.urls.robloxStudioAuthProtocol) {
+				this._urls.robloxStudioAuthProtocol =
+					props.urls.robloxStudioAuthProtocol;
+			}
+
+			if (props.urls.placeLauncherUrl) {
+				this._urls.placeLauncherUrl = props.urls.placeLauncherUrl;
+			}
+		}
+	}
+
+	public buildAuthedProtocolUrl(
+		request: BuildAuthedProtocolUrlParameters<T>,
+	): string {
+		if (
+			request.type === this._urls.robloxStudioAuthProtocol &&
+			request.state &&
+			request.code
+		) {
+			return `${this._urls.robloxStudioAuthProtocol}://?state=${request.state}&code=${request.code}`;
+		}
+
+		const params: string[] = ["1"];
+
+		if (request.launchMode) params.push(`launchmode:${request.launchMode}`);
+		if (request.gameInfo) params.push(`gameinfo:${request.gameInfo}`);
+		if (request.launchTime) params.push(`launchtime:${request.launchTime}`);
+		if (request.baseUrl) params.push(`baseUrl:${request.baseUrl}`);
+
+		if (request.otherParams) {
+			for (const key in request.otherParams) {
+				const value = request.otherParams[key];
+				if (key === value) {
+					params.push(key);
+				} else if (value !== undefined && value !== null) {
+					params.push(`${key}:${encodeURIComponent(value)}`);
+				}
+			}
+		}
+
+		return `${request.type}:${params.join("+")}`;
+	}
+
+	public buildAuthedPlaceLauncherUrl(
+		request: BuildAuthedPlaceLauncherURLParameters<U>,
+	): string {
+		const url = new URL(this._urls.placeLauncherUrl);
+		const stringifiedParameters: Record<string, string> = {};
+		for (const key in request) {
+			const value = request[key as keyof typeof request];
+
+			if (value !== undefined && value !== null) {
+				stringifiedParameters[key] = String(value);
+			}
+		}
+
+		url.search = new URLSearchParams(stringifiedParameters).toString();
+		return url.toString();
+	}
+
+	public parseAuthedProtocolUrl(
+		url: string,
+	): BuildAuthedProtocolUrlParameters<T> | null {
+		if (url.startsWith(`${this._urls.robloxStudioAuthProtocol}:`)) {
+			const urlObj = new URL(url);
+			return {
+				type: this._urls.robloxStudioAuthProtocol,
+				state: urlObj.searchParams.get("state") ?? undefined,
+				code: urlObj.searchParams.get("code") ?? undefined,
+			};
+		}
+
+		const isPlayer = url.startsWith(`${this._urls.robloxPlayerProtocol}:1`);
+		const isStudio = url.startsWith(`${this._urls.robloxStudioProtocol}:1`);
+		if (!isPlayer && !isStudio) {
+			return null;
+		}
+
+		const split = url.split("+");
+
+		const type = isPlayer
+			? this._urls.robloxPlayerProtocol
+			: this._urls.robloxStudioProtocol;
+
+		const params: BuildAuthedProtocolUrlParameters<T> = {
+			type,
+		};
+
+		for (let i = 1; i < split.length; i++) {
+			const item = split[i];
+			const [key, value] = item.split(":");
+			if (!value) continue;
+
+			switch (key.toLowerCase()) {
+				case "launchmode": {
+					params.launchMode = value as AuthedLaunchMode;
+					break;
+				}
+				case "gameinfo": {
+					params.gameInfo = value;
+					break;
+				}
+				case "launchtime": {
+					params.launchTime = value;
+					break;
+				}
+				default: {
+					params.otherParams ??= {};
+					params.otherParams[key] = decodeURIComponent(value);
+				}
+			}
+		}
+
+		return params;
+	}
+
+	public parseAuthedPlaceLauncherUrl(
+		urlStr: string,
+	): BuildAuthedPlaceLauncherURLParameters<U> | null {
+		try {
+			const url = new URL(urlStr);
+
+			const request = url.searchParams.get("request");
+			if (!request) return null;
+
+			const obj: BuildAuthedPlaceLauncherURLParameters<U> = {
+				request: request as BuildAuthedPlaceLauncherRequest,
+			};
+
+			for (const [key, value] of url.searchParams) {
+				let valueToSet: number | boolean | string;
+				if (value === "true") {
+					valueToSet = true;
+				} else if (value === "false") {
+					valueToSet = false;
+				} else {
+					const parsedNumber = Number(value);
+
+					if (!Number.isNaN(parsedNumber)) {
+						valueToSet = parsedNumber;
+					} else {
+						valueToSet = value;
+					}
+				}
+
+				// @ts-expect-error: Fine tbh
+				obj[key] = valueToSet;
+			}
+
+			return obj;
+		} catch {
+			return null;
+		}
+	}
+}