mobbin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomas Roda
+
+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,197 @@
+# Mobbin CLI
+
+Small Node.js CLI + SDK for calling Mobbin's JSON endpoints under `https://mobbin.com/api/*`.
+
+Some endpoints are public, others require an authenticated `mobbin.com` session cookie.
+
+## Requirements
+
+- Node.js `>=18` (uses built-in `fetch`)
+
+## Quickstart (run from this repo)
+
+```bash
+./mobbin-cli.js --help
+./mobbin-cli.js trending-apps --platform ios
+./mobbin-cli.js trending-sites
+./mobbin-cli.js searchable-apps --platform web
+```
+
+## Install As `mobbin` (recommended)
+
+This repo includes a `package.json` with a `bin` entry, so you can link it once and then use `mobbin` anywhere.
+
+```bash
+cd /path/to/tools/mobbin
+npm link
+
+mobbin --help
+mobbin trending-apps --platform ios
+```
+
+If you do not want to use `npm link`, a simple shell alias also works:
+
+```bash
+alias mobbin="/path/to/tools/mobbin/mobbin-cli.js"
+mobbin trending-sites
+```
+
+## Authentication (cookies)
+
+Auth-gated endpoints require a valid `mobbin.com` session cookie.
+
+The CLI will try to find cookies automatically for auth-gated commands:
+
+- `MOBBIN_COOKIE` / `--cookie`
+- `MOBBIN_COOKIE_FILE` / `--cookie-file`
+- Common local files like `~/.config/mobbin/cookie.txt`
+- macOS only: local browser cookie stores (Safari, Chrome, Edge, Brave, Chromium)
+- If run in a TTY and no cookies are found for an auth-gated command, the CLI will open `mobbin.com` and prompt you to log in, then retry cookie discovery.
+
+You can provide cookies explicitly in three ways (highest priority first):
+
+1. `--cookie "name=value; name2=value2"`
+2. `--cookie-file <path>` (either):
+   - Netscape cookie file (common export format)
+   - Playwright storage state JSON (the CLI extracts cookies for `mobbin.com`)
+   - JSON array of cookie objects (common browser export format)
+3. `MOBBIN_COOKIE` env var
+
+Examples:
+
+```bash
+mobbin search --query "login" --platform ios --experience apps --cookie "session=..."
+
+mobbin search --query "login" --cookie-file ./cookies.txt
+mobbin search --query "login" --cookie-file ./storage-state.json
+
+MOBBIN_COOKIE="session=..." mobbin recent-searches
+```
+
+### Common auth errors
+
+- `401` or `{ error: { message: "unauthenticated" } }`: missing/expired cookie
+- `400` from `content-apps`: often needs auth and/or server-side state (Mobbin seems to expect a non-null `searchRequestId` in some flows)
+
+### One-time setup: save cookies to a file
+
+This opens `mobbin.com` in your browser (macOS) and then saves a cookie string to `~/.config/mobbin/cookie.txt`:
+
+```bash
+mobbin auth save-cookie --out ~/.config/mobbin/cookie.txt
+```
+
+If your Mobbin login is in Safari, you can force Safari cookie reading:
+
+```bash
+mobbin auth save-cookie --cookie-from safari
+```
+
+If Mobbin is logged in under a non-default Chrome profile, pass the profile directory name:
+
+```bash
+mobbin auth save-cookie --cookie-from chrome --cookie-profile "Profile 1"
+```
+
+Security note: this file contains session cookies. Treat it like a password.
+
+## Commands
+
+All commands output pretty JSON by default.
+
+- Add `--raw` to print raw (non-JSON) output
+- Add `--compact` to print compact JSON (1 line)
+
+Public endpoints (work without cookies):
+
+```bash
+mobbin trending-apps --platform ios
+mobbin trending-sites
+mobbin searchable-sites
+mobbin searchable-apps --platform ios
+mobbin trending-keywords --platform ios
+mobbin dictionary
+mobbin trending-filter-tags --platform ios --experience apps
+```
+
+Auth-gated endpoints (require cookies):
+
+```bash
+mobbin search --query "login" --platform ios --experience apps
+mobbin popular-apps --platform ios --limit 10
+mobbin app-versions --app-id <uuid>
+mobbin screen-info --screen-id <uuid>
+mobbin recent-searches
+mobbin content-apps --platform ios --tab latest --page-size 24
+```
+
+## Download Screenshots
+
+Mobbin API responses often include Supabase storage URLs (e.g. `https://*.supabase.co/storage/v1/object/public/...`).
+Those URLs may not be directly browsable, but Mobbin serves the same assets via `bytescale.mobbin.com`.
+
+Use `download` to fetch screenshots to disk:
+
+```bash
+# Download all screenshots for an app (all versions)
+mobbin download --app-id <uuid> --out-dir ./out
+
+# Download a single screen
+mobbin download --screen-id <uuid> --out-dir ./out
+
+# Download all full-page screens for a site (latest version)
+mobbin download --site-id <uuid> --out-dir ./out
+
+# Download from a Mobbin site URL (any /sites/... URL works)
+mobbin download "https://mobbin.com/sites/<anything>-<siteId>" --out-dir ./out
+
+# Download one or many URLs (Supabase or Bytescale URLs)
+mobbin download "https://ujasntkfphywizsdaapi.supabase.co/storage/v1/object/public/content/app_screens/<file>.png" --out-dir ./out
+
+# Download from a Mobbin screen page URL
+mobbin download "https://mobbin.com/screens/<uuid>" --out-dir ./out
+```
+
+`extract` is an alias of `download` (same flags).
+
+Tip: `download` caches Mobbin's Bytescale mapping in `~/.config/mobbin/bytescale.json`. Use `--bytescale-refresh` if downloads suddenly start failing.
+
+Notes:
+
+- `download --app-id`, `--screen-id`, and `--site-id` require auth cookies
+- `--app-id`, `--screen-id`, and `--site-id` accept comma-separated lists
+- `download --site-id` fetches the site's `/sections` page HTML and extracts `content/app_fullpage_screens/*` URLs (if this breaks, pass the exact `/sites/.../<siteVersionId>/sections` URL)
+- `--platform` is typically one of `ios|android|web`
+- `--experience` defaults to `apps` (Mobbin also uses other values in the UI)
+- `content-apps --tab` maps to sorting behavior:
+  - `latest` (sort by `publishedAt`, also hides non-ideal apps)
+  - `popular` (sort by `popularity`)
+  - `top` (sort by `rating`)
+
+## Raw API Calls
+
+Use `call` to hit any endpoint (useful for recon / experimenting).
+
+```bash
+mobbin call /api/search-bar/fetch-trending-sites --method POST --data "{}"
+mobbin call /api/search-bar/fetch-trending-apps --method POST --data '{"platform":"ios"}'
+```
+
+Tip: `--data` must be valid JSON.
+
+## SDK
+
+`mobbin-sdk.js` exports:
+
+- `MobbinClient` (a small fetch wrapper)
+- `buildContentAppsPayload()` (helper for `/api/content/fetch-apps`)
+
+Example:
+
+```js
+import { MobbinClient } from "./mobbin-sdk.js";
+
+const client = new MobbinClient({ cookie: process.env.MOBBIN_COOKIE });
+const apps = await client.fetchTrendingApps({ platform: "ios" });
+console.log(apps);
+```