Metadata-Version: 2.4
Name: session-bundle-kit
Version: 0.3.6
Summary: Playwright storage_state zip export — backup sessions, diff bundles, MLX cookie pull/push. CLI: session-bundle.
Project-URL: Homepage, https://github.com/session-bundle-kit/session-bundle-kit
Project-URL: Documentation, https://github.com/session-bundle-kit/session-bundle-kit#readme
Project-URL: Repository, https://github.com/session-bundle-kit/session-bundle-kit
Project-URL: Issues, https://github.com/session-bundle-kit/session-bundle-kit/issues
Author: session-bundle-kit contributors
License-Expression: MIT
License-File: LICENSE
Keywords: browser-backup,browser-session-migration,chrome-136,context-backup,cookie-export,indexeddb-manifest,localstorage-backup,multilogin-cookies,playwright-storage-state,portable-session,session-bundle,session-diff,session-export,session-restore,storage-state,zip-export
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-httpx>=0.34; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: mlx
Requires-Dist: httpx>=0.27; extra == 'mlx'
Description-Content-Type: text/markdown

# session-bundle-kit

**Playwright session export & backup** — zip storage_state cookies and localStorage; MLX cookie pull/push for profile migration.

[![PyPI version](https://img.shields.io/pypi/v/session-bundle-kit.svg)](https://pypi.org/project/session-bundle-kit/)
[![Python versions](https://img.shields.io/pypi/pyversions/session-bundle-kit.svg)](https://pypi.org/project/session-bundle-kit/)
[![License: MIT](https://img.shields.io/pypi/l/session-bundle-kit.svg)](https://pypi.org/project/session-bundle-kit/)

```bash
pip install session-bundle-kit
session-bundle export state.json -o bundle.zip
```

CLI: **`session-bundle`** · Python **3.10+** · optional **`[mlx]`** for Launcher helpers

> **Partner (optional):** Restore sessions into **isolated MLX profiles** — not a shared Chrome `user-data-dir`. [Multilogin X](https://multilogin.com?a_aid=saas) · `SAAS50` / `MIN50` on eligible new purchases. Export/diff works offline without MLX. [Affiliate disclosure](docs/AFFILIATE.md) · [Multilogin promo codes](https://anti-detect.github.io/).

**Playwright session export & backup** — zip `storage_state` cookies and localStorage; MLX cookie pull/push for profile migration.

Export and compare **browser session bundles** — cookies, `localStorage`, `sessionStorage`, and IndexedDB metadata — from Playwright storage state JSON.

Pure Python zip format. Optional MLX push for cookie import into antidetect profiles.

## Problem

Playwright `storage_state.json` is a single file mixing cookies and per-origin storage. Teams need:

- Portable **zip bundles** with a manifest for CI and backups
- **Dry-run validation** before restoring sessions
- **Diff** between two session snapshots
- Push cookies into **MLX profiles** after export

## Install

```bash
pip install session-bundle-kit
```

MLX profile push:

```bash
pip install session-bundle-kit[mlx]
```

## Quick start

```bash
# Export Playwright storage state -> bundle zip
session-bundle export --playwright-context ./state.json -o bundle.zip

# Validate bundle (dry-run default)
session-bundle import bundle.zip --dry-run

# Compare two bundles
session-bundle diff bundle_a.zip bundle_b.zip
```

## Bundle format (spec v1)

```
bundle.zip
├── manifest.json          # spec, version, counts, source
├── cookies.json           # Playwright cookie list
├── origins/
│   └── https%3A%2F%2Fexample.com.json   # localStorage + sessionStorage
└── indexeddb/
    └── metadata.json      # IDB database names/versions (metadata only)
```

IndexedDB **metadata** is included for audit/diff; full IDB binary export is out of scope.

`manifest.json` example:

```json
{
  "spec": "session-bundle-v1",
  "version": 1,
  "source": "playwright-storage-state",
  "cookie_count": 12,
  "origin_count": 3,
  "indexeddb_count": 0
}
```

## CLI

| Command | Description |
|---------|-------------|
| `session-bundle export --playwright-context FILE -o OUT.zip` | Create bundle from Playwright state |
| `session-bundle import FILE --dry-run` | Validate bundle without writing (default) |
| `session-bundle diff A.zip B.zip` | Cookie domain + storage/IDB diff |
| `session-bundle mlx-pull --profile-id UUID -o bundle.zip` | Export MLX profile cookies → bundle (`[mlx]`) |
| `session-bundle mlx-push --profile-id UUID --bundle FILE` | Import bundle cookies to MLX (`[mlx]`) |
| `session-bundle mlx-push ... --dry-run` | Validate bundle; no MLX API calls |

## API

```python
from session_bundle_kit import export_playwright_context, validate_bundle, diff_bundles

export_playwright_context("state.json", "bundle.zip")
report = validate_bundle("bundle.zip")
diff = diff_bundles("old.zip", "new.zip")
```

Restore to Playwright:

```python
from session_bundle_kit.bundle import SessionBundle

bundle = SessionBundle.read_zip("bundle.zip")
context = await browser.new_context(storage_state=bundle.to_playwright_storage_state())
```

## MLX pull / push (`[mlx]` extra)

Round-trip **cookies** between MLX profiles and neutral **session-bundle-v1** zips. Storage/IDB in bundles from Playwright export are manifest-only on push; MLX Launcher APIs move cookies only.

**Pull** (profile → zip):

1. `GET api.multilogin.com/profile/unlock?profile_ids=UUID`
2. `POST launcher.mlx.yt:45001/api/v1/cookies/export`

**Push** (zip → profile):

1. Validate bundle (`--dry-run` stops here)
2. `GET api.multilogin.com/profile/unlock?profile_ids=UUID`
3. `POST launcher.mlx.yt:45001/api/v1/cookies/import`

```bash
export MLX_TOKEN="..."

# Export MLX profile session to portable bundle
session-bundle mlx-pull --profile-id PROFILE_UUID -o bundle.zip

# Validate before import
session-bundle mlx-push --profile-id PROFILE_UUID --bundle bundle.zip --dry-run

# Import cookies into target profile
session-bundle mlx-push --profile-id PROFILE_UUID --bundle bundle.zip
```

Peer pattern for Launcher lifecycle: see `cdp-connect-kit` MLX integration docs.

## When login sessions break after profile switch (playbook)

Sites re-challenge when cookies land on a **new fingerprint or IP**. Use bundles to move **stored** credentials deliberately — not as a bypass.

| Symptom | Likely cause | Next step |
|---------|--------------|-----------|
| Import ok, still logged out | Domain/subdomain mismatch, expired cookies | `session-bundle diff` old vs new; fix with [cookie-jar-bridge](https://pypi.org/project/cookie-jar-bridge/) |
| Step-up / CAPTCHA after restore | IP or fingerprint drift | Match proxy lane; probe with [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) |
| MLX push succeeds, site fails | Cookies only — no `localStorage` on target | Restore storage via Playwright `storage_state` on same profile |
| Migration metadata only | `antidetect-importer` left `_cookies` sidecar | `mlx-pull` source → edit → `mlx-push --dry-run` → push |

**Session migration pipeline:**

```bash
session-bundle export --playwright-context state.json -o bundle.zip
session-bundle import bundle.zip --dry-run
session-bundle mlx-push --profile-id TARGET_UUID --bundle bundle.zip --dry-run
export MLX_TOKEN=...
session-bundle mlx-push --profile-id TARGET_UUID --bundle bundle.zip
cdp-probe mlx --profile-id TARGET_UUID --url https://your-app.example  # verify session + exposure
```


**Coupon hub:** [Multilogin promo codes](https://anti-detect.github.io/) — guides for `SAAS50` / `MIN50`, pricing comparisons, and workflow playbooks.
**Migration partner note:** Multi-account moves use `mlx-pull` / `mlx-push` on [Multilogin X](https://multilogin.com?a_aid=saas) Launcher. Code `SAAS50` (browser) — verify eligibility before checkout. Full coupons: `session-bundle --show-deal`.

Treat bundle zips as **secrets** — same sensitivity as password files.

## When Chrome `user-data-dir` fails in 2026

Starting with **Chrome 136** (March 2025), Google changed how remote debugging works on the default profile. Per the [Chrome Developers blog](https://developer.chrome.com/blog/remote-debugging-port):

- `--remote-debugging-port` and `--remote-debugging-pipe` are **ignored** when targeting Chrome's **default** user data directory.
- You must pass a **custom** `--user-data-dir` pointing to a non-default profile path for CDP to bind.
- The change targets cookie theft via remote debugging after [App-Bound Encryption](https://developer.chrome.com/blog/app-bound-encryption); Chrome for Testing still supports the older automation workflow.

**Practical impact:** copying your daily `Default` profile and launching with `--remote-debugging-port` no longer works on stock Chrome 136+. Session-bundle-kit sidesteps this by exporting **Playwright `storage_state.json`** (cookies + origin storage) into portable zips — restore via `new_context(storage_state=...)` on antidetect or isolated profiles instead of attaching CDP to your real Chrome profile.

Enterprise admins can still control remote debugging via the [Allow remote debugging](https://support.google.com/chrome/a/answer/2657289) Chrome policy on managed devices.

## Limitations

- **No live IDB export** — IndexedDB section is metadata manifest only.
- **sessionStorage** preserved in bundle format but Playwright native export may omit it; include in custom state JSON if needed.
- **mlx-push** imports cookies only; storage must be restored via Playwright or profile sync separately.
- **Secrets** — bundles contain session secrets; treat zip files as credentials. Import warns on likely plaintext passwords in web storage.

## Production

Export sessions to portable zips, validate with `mlx-push --dry-run`, then import cookies into MLX profiles after `antidetect-importer` migration or failed login on a new profile.

**Partner note (affiliate):** When restoring sessions into **isolated Multilogin X** profiles (not shared Chrome `user-data-dir`), Launcher cookie import pairs with profile-level proxy and fingerprint. Eligible new browser purchases may accept code **`SAAS50`** at [multilogin.com](https://multilogin.com?a_aid=saas) — verify terms before checkout. Export/diff/validate work without MLX. Full disclosure: [docs/AFFILIATE.md](docs/AFFILIATE.md). Deals hub: [anti-detect.github.io](https://anti-detect.github.io/). Coupon details only via `session-bundle --show-deal` (never printed by default).

**FAQ:** [docs/FAQ.md](docs/FAQ.md) — Playwright storage_state export, Chrome 136 CDP, MLX cookie import.


## Related tools (on PyPI)

| Package | CLI | Role |
|---------|-----|------|
| [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) | `cdp-probe` | CDP / WebDriver exposure score |
| [cookie-jar-bridge](https://pypi.org/project/cookie-jar-bridge/) | `cookie-bridge` | Netscape ↔ Playwright cookies |
| [proxy-lane-checker](https://pypi.org/project/proxy-lane-checker/) | `proxy-lane` | Proxy TCP / HTTP / geo / DNSBL |
| [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) | `fp-coherence` | UA / screen / timezone lint |

**Toolkit pipeline:** `proxy-lane check` → `fp-coherence audit` → automate → `cdp-probe run` → `cookie-bridge validate`

## License

MIT

---

**Production antidetect (partner):** [Multilogin X](https://multilogin.com?a_aid=saas) · Code `SAAS50` (-50% browser) · [MIN50](https://multilogin.com?a_aid=saas) (-50% cloud phone)  
Affiliate disclosure — we may earn a commission; offers change on the vendor site. More scripts: [@Multilogin_Scripts_Bot](https://t.me/Multilogin_Scripts_Bot) · [Multilogin promo codes](https://anti-detect.github.io/)
