async_instalib 0.1.0__py3-none-any.whl

async_instalib/__init__.py

@@ -0,0 +1,225 @@
+"""Async access to Instagram's mobile API."""
+
+from .auth import TwoFactorMethod  # Select the pending login's verification method.
+from .client import Instagram  # Own one account's async resources and connection pool.
+from .config import (
+    AuthOptions,  # Customize login metadata and supported payload parameters.
+    RequestPolicy,  # Bound account work and control response-driven pauses.
+)
+from .config.about import AboutOptions  # Configure the captured account-information screen request.
+from .config.comments import CommentListOptions  # Choose comment sort order and continue pages.
+from .config.content import (
+    ContentOptions,  # Configure one profile content page.
+    MetadataOptions,  # Override story/highlight query parameters.
+    ProfileOptions,  # Configure captured profile entry context.
+    ReelsOptions,  # Configure one recorded reels-grid page.
+    RelatedOptions,  # Configure related-account suggestions.
+    RepostsOptions,  # Configure repost metadata pages without playback hydration.
+    TaggedOptions,  # Configure tagged-media pages and explicit continuations.
+)
+from .config.devices import (
+    GALAXY_S24,  # Samsung Galaxy S24 (SM-S921U), Android 14.
+    GALAXY_S25,  # Samsung Galaxy S25 (SM-S931B), Android 16; the default.
+    GALAXY_S25_ULTRA,  # Samsung Galaxy S25 Ultra (SM-S938B), Android 16.
+    INFINIX_X6880,  # Infinix X6880, Android 15.
+    PIXEL_9_PRO,  # Google Pixel 9 Pro, Android 17.
+    AndroidDevice,  # A real phone's fields in the Instagram user agent.
+)
+from .config.direct import InboxOptions  # Choose how many threads and messages the inbox returns.
+from .config.metadata import (
+    AboutDecodeOptions,  # Bound inert account-information bundle decoding.
+    HighlightItemsOptions,  # Configure one selected highlight item read.
+)
+from .config.muted import MutedDecodeOptions  # Bound inert muted-account screen decoding.
+from .config.people import (
+    MutualFollowersOptions,  # Configure the captured mutual-followers preview.
+    PeopleListOptions,  # Configure bounded relationship lists.
+    SearchOptions,  # Configure one account-search page.
+)
+from .config.posts import (
+    CarouselItem,  # Attach tags and alt text to one carousel photo.
+    EditOptions,  # Replace a post's caption and set alt text, location, or added tags.
+    HighlightChanges,  # Rename a highlight or add and remove stories.
+    PostOptions,  # Configure a feed photo or carousel.
+    ReelOptions,  # Configure a reel, including whether it appears in the main grid.
+    StoryOptions,  # Configure a story's caption and Close Friends audience.
+    UserTag,  # Tag one person at a position on a photo.
+)
+from .config.relationship_lists import (
+    CloseFriendsListOptions,  # Configure the captured member page.
+    FollowRequestsListOptions,  # Configure the incoming-request list.
+    MutedListOptions,  # Configure the muted-accounts screen envelope.
+)
+from .config.relationships import (
+    ActionOptions,  # Customize explicit relationship request metadata.
+    BlockOptions,  # Select block scope and explicit provider metadata.
+    CloseFriendsOptions,  # Configure one-member Close Friends edits.
+    FavoritesOptions,  # Configure one-member feed Favorites edits.
+    MuteOptions,  # Choose one captured content category to mute.
+    NotificationOptions,  # Choose content and notification preference.
+)
+from .exceptions import (
+    AccountPaused,  # Require explicit review before further account requests.
+    AccountRestricted,  # Surface restrictions without automatic retries.
+    APIError,  # Report otherwise unclassified provider failures.
+    BadCredentials,  # Report a rejected username or password.
+    ChallengeRequired,  # Surface account-owner verification requirements.
+    InstagramError,  # Catch all expected SDK failures.
+    LoginFlowUnsupported,  # Identify a provider flow not yet established.
+    LoginRequired,  # Identify an absent or rejected session.
+    NetworkError,  # Report uncertain network outcomes without replaying writes.
+    PersonNotFound,  # Identify an unavailable username from the direct profile lookup.
+    ProtocolError,  # Identify invalid or unsupported provider responses.
+    RateLimited,  # Expose the provider's wait hint.
+    RequestBudgetExceeded,  # Report local request or login budget exhaustion.
+    SessionInUse,  # Prevent two owners of the same session file.
+    TwoFactorRequired,  # Continue a password login with a verification code.
+)
+from .models import (
+    ClientOptions,  # Configure bounded connections, timeouts, and an explicit proxy.
+    ClientProfile,  # Configure public mobile app metadata.
+    User,  # Read stable account fields and explicit raw provider data.
+)
+from .models.about import (
+    AboutAccount,  # Read named account-information state without executing UI code.
+    AboutState,  # Preserve a named state and its initial provider value.
+)
+from .models.activity import (
+    Notification,
+)  # Read one activity-feed row: comment, mention, like, follow.
+from .models.comments import Comment  # Read one comment or reply with its author and counts.
+from .models.content import Media  # Read media identity, caption, and provider metadata.
+from .models.direct import (
+    Message,  # Read one direct message; pass it to reply, react, edit, or unsend.
+    Thread,  # Read one conversation with its newest messages.
+)
+from .models.muted import MutedPerson  # Read verified account IDs and nullable mute categories.
+from .models.pagination import (
+    Continuation,  # Bind opaque cursors to their originating request.
+    Page,  # Return one explicit result page.
+    PageContext,  # Identify the account, operation, target, and query.
+)
+from .models.people import (
+    PersonProfile,  # Read profile details without inventing missing values.
+    PersonSummary,  # Read partial person identity and relationship fields.
+    Relationship,  # Represent account-relative relationship flags.
+)
+from .models.posts import (
+    Place,  # Tag a location found with posts.places.search().
+    Publication,  # Read a publish acknowledgement and its processing status.
+)
+from .models.stories import (
+    Highlight,  # Read one highlight identity and metadata.
+    HighlightCover,  # Preserve cover media metadata.
+    HighlightImage,  # Read a highlight cover image variant.
+    HighlightItems,  # Read one selected highlight's typed media items.
+    HighlightTray,  # Read typed highlight tray entries.
+    StoryAuthor,  # Preserve partial story author identity without inventing a username.
+    StoryCollection,  # Read a typed story response with raw metadata.
+    StoryItem,  # Read typed story media and optional timestamps.
+    StoryReel,  # Group accessible stories under their owner.
+)
+from .models.uploads import (
+    Audio,  # Send an MP4/M4A recording as a voice message.
+    Photo,  # Publish a JPEG unchanged, with its dimensions read from the file.
+    Video,  # Publish an MP4 unchanged, with an optional first-frame cover.
+)
+from .resources.relationships import RelationshipActionResult  # Read status-only acknowledgements.
+from .session import (
+    Device,  # Persist device identity across client restarts.
+    Session,  # Import, save, and restore private session state.
+)
+
+__all__ = [
+    "Audio",
+    "AndroidDevice",
+    "GALAXY_S24",
+    "GALAXY_S25",
+    "GALAXY_S25_ULTRA",
+    "INFINIX_X6880",
+    "PIXEL_9_PRO",
+    "InboxOptions",
+    "Message",
+    "Thread",
+    "Notification",
+    "Comment",
+    "CommentListOptions",
+    "CarouselItem",
+    "EditOptions",
+    "HighlightChanges",
+    "Photo",
+    "Place",
+    "PostOptions",
+    "Publication",
+    "ReelOptions",
+    "StoryOptions",
+    "UserTag",
+    "Video",
+    "MutedDecodeOptions",
+    "MutedPerson",
+    "HighlightItemsOptions",
+    "HighlightItems",
+    "StoryAuthor",
+    "MutualFollowersOptions",
+    "FollowRequestsListOptions",
+    "FavoritesOptions",
+    "MutedListOptions",
+    "CloseFriendsOptions",
+    "CloseFriendsListOptions",
+    "AboutDecodeOptions",
+    "AboutAccount",
+    "AboutState",
+    "StoryItem",
+    "StoryReel",
+    "StoryCollection",
+    "HighlightImage",
+    "HighlightCover",
+    "Highlight",
+    "HighlightTray",
+    "AboutOptions",
+    "TaggedOptions",
+    "RepostsOptions",
+    "ReelsOptions",
+    "BlockOptions",
+    "RelatedOptions",
+    "ActionOptions",
+    "MuteOptions",
+    "NotificationOptions",
+    "RelationshipActionResult",
+    "PersonNotFound",
+    "ProfileOptions",
+    "ContentOptions",
+    "MetadataOptions",
+    "Media",
+    "SearchOptions",
+    "PeopleListOptions",
+    "PersonSummary",
+    "PersonProfile",
+    "Relationship",
+    "Page",
+    "Continuation",
+    "PageContext",
+    "AuthOptions",
+    "RequestPolicy",
+    "AccountPaused",
+    "RequestBudgetExceeded",
+    "SessionInUse",
+    "Instagram",
+    "Session",
+    "Device",
+    "ClientOptions",
+    "ClientProfile",
+    "User",
+    "TwoFactorMethod",
+    "InstagramError",
+    "APIError",
+    "AccountRestricted",
+    "BadCredentials",
+    "ChallengeRequired",
+    "LoginFlowUnsupported",
+    "LoginRequired",
+    "NetworkError",
+    "ProtocolError",
+    "RateLimited",
+    "TwoFactorRequired",
+]

async_instalib/__main__.py

@@ -0,0 +1,6 @@
+"""Run the interactive CLI with python -m async_instalib."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

async_instalib/auth/__init__.py

@@ -0,0 +1,8 @@
+"""Auth package exports."""
+
+from .service import (
+    Auth,  # Expose the Auth contract.
+    TwoFactorMethod,  # Expose the TwoFactorMethod contract.
+)
+
+__all__ = ["Auth", "TwoFactorMethod"]

async_instalib/auth/bloks.py

@@ -0,0 +1,146 @@
+"""Read the small data subset needed from Bloks; never execute server expressions."""
+
+import json
+from collections.abc import Iterator
+from typing import Any
+
+from ..exceptions import LoginFlowUnsupported, ProtocolError
+
+
+def strings(value: Any) -> Iterator[str]:
+    """Walk JSON values without treating object keys as executable instructions."""
+    pending = [value]
+    while pending:
+        item = pending.pop()
+        if isinstance(item, str):
+            yield item
+        elif isinstance(item, dict):
+            pending.extend(reversed(list(item.values())))
+        elif isinstance(item, list):
+            pending.extend(reversed(item))
+
+
+def quoted_strings(expression: str) -> Iterator[str]:
+    decoder, position = json.JSONDecoder(), 0
+    while position < len(expression):
+        if expression[position] != '"':
+            position += 1
+            continue
+        try:
+            value, position = decoder.raw_decode(expression, position)
+        except ValueError:
+            position += 1
+            continue
+        if isinstance(value, str):
+            yield value
+
+
+def expression_at(text: str, position: int) -> Any:
+    """Parse one parenthesized value with bounded depth; operators remain inert strings."""
+    stack: list[list[Any]] = []
+    decoder = json.JSONDecoder()
+    value: Any
+    while position < len(text):
+        character = text[position]
+        if character.isspace() or character == ",":
+            position += 1
+        elif character == "(":
+            stack.append([])
+            if len(stack) > 128:
+                raise ProtocolError("Bloks expression nesting exceeds the supported limit.")
+            position += 1
+        elif character == ")":
+            if not stack:
+                break
+            value = stack.pop()
+            if not stack:
+                return value
+            stack[-1].append(value)
+            position += 1
+        elif character == '"':
+            value, position = decoder.raw_decode(text, position)
+            if not stack:
+                break
+            stack[-1].append(value)
+        else:
+            end = position
+            while end < len(text) and not text[end].isspace() and text[end] not in "(),":
+                end += 1
+            atom = text[position:end]
+            try:
+                value = json.loads(atom)
+            except ValueError:
+                value = atom
+            if not stack:
+                break
+            stack[-1].append(value)
+            position = end
+    raise ProtocolError("Incomplete Bloks data expression.")
+
+
+def server_parameters(payload: dict[str, Any], action: str) -> dict[str, Any]:
+    """Read the literal server-parameter map immediately following the named action."""
+    marker = json.dumps(action)
+    for text in strings(payload):
+        position = text.find(marker)
+        if position < 0:
+            continue
+        start = text.find("(", position + len(marker))
+        if start < 0:
+            continue
+        try:
+            node = expression_at(text, start)
+        except (ValueError, ProtocolError):
+            continue
+        if not isinstance(node, list) or len(node) != 3:
+            continue
+        keys, values = node[1:]
+        if (
+            not isinstance(keys, list)
+            or not isinstance(values, list)
+            or len(keys) != len(values)
+            or not keys
+            or keys[0] != values[0]
+            or not all(isinstance(k, str) for k in keys[1:])
+            or any(isinstance(v, (list, dict)) for v in values[1:])
+        ):
+            continue
+        return dict(zip(keys[1:], values[1:], strict=True))
+    raise LoginFlowUnsupported("Instagram's login screen did not expose supported action data.")
+
+
+def account_access_context(payload: dict[str, Any]) -> str:
+    for item in payload.get("layout", {}).get("bloks_payload", {}).get("data", []):
+        data = item.get("data", {}) if isinstance(item, dict) else {}
+        if not isinstance(data, dict) or data.get("key") != "CAA_ACCOUNT_ACCESS_CONTEXT:aac":
+            continue
+        initial = data.get("initial")
+        if isinstance(initial, str) and initial:
+            return initial
+        expression = data.get("initial_lispy")
+        if isinstance(expression, str):
+            value = next(quoted_strings(expression), None)
+            if value:
+                return value
+    raise LoginFlowUnsupported("Instagram did not issue an account access context.")
+
+
+def login_result(payload: dict[str, Any]) -> dict[str, Any]:
+    action = payload.get("layout", {}).get("bloks_payload", {}).get("action", "")
+    if not isinstance(action, str):
+        raise ProtocolError("Instagram's login response has no supported action data.")
+    for value in quoted_strings(action):
+        if "login_response" not in value:
+            continue
+        try:
+            parsed = json.loads(value)
+            result = json.loads(parsed["login_response"])
+            headers = json.loads(parsed.get("headers") or "{}")
+        except (ValueError, KeyError, TypeError):
+            continue
+        if isinstance(result, dict) and isinstance(headers, dict):
+            return {"result": result, "headers": headers}
+    raise LoginFlowUnsupported(
+        "Instagram returned a verification or login continuation this client does not support. "
+        "Complete verification in the app; no automatic password retry was made."
+    )

async_instalib/auth/caa.py

@@ -0,0 +1,254 @@
+"""CAA password flow derived from the Android 452.1 login capture."""
+
+import json
+import time
+from typing import Any
+from uuid import uuid4
+
+import httpx
+
+from ..exceptions import LoginFlowUnsupported, ProtocolError
+from ..transport import APIResponse, RequestData, Transport
+from . import bloks
+from .password import PasswordKey
+
+PREPARE = "com.bloks.www.bloks.caa.login.process_client_data_and_redirect"
+OAUTH = "com.bloks.www.caa.login.oauth.token.fetch.async"
+LOGIN = "com.bloks.www.bloks.caa.login.async.send_login_request"
+
+
+class CAALogin:
+    """Obtain fresh server context, then submit one encrypted password exchange."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+        self._options = transport.auth_options
+
+    async def login(self, username: str, password: str) -> APIResponse:
+        session = self._transport.session
+        device = session.device
+        waterfall_id = str(uuid4())
+        nonce = await self._transport.request(
+            "POST",
+            "attestation/create_android_keystore/",
+            {"app_scoped_device_id": device.id, "key_hash": ""},
+        )
+        challenge_nonce = nonce.get("challenge_nonce")
+        if not isinstance(challenge_nonce, str) or not challenge_nonce:
+            raise ProtocolError("Instagram did not supply a device challenge nonce.")
+        screen = await self._action(
+            PREPARE,
+            {
+                "is_from_logged_out": False,
+                "logged_out_user": "",
+                "qpl_join_id": None,
+                "family_device_id": device.family_id,
+                "device_id": device.android_id,
+                "offline_experiment_group": self._options.offline_experiment_group,
+                "waterfall_id": waterfall_id,
+                "logout_source": "",
+                "show_internal_settings": False,
+                "last_auto_login_time": 0,
+                "disable_auto_login": False,
+                "qe_device_id": device.id,
+                "use_auto_login_interstitial": True,
+                "disable_recursive_auto_login_interstitial": True,
+                "auto_login_interstitial_experiment_group_name": "",
+                "is_from_logged_in_switcher": False,
+                "switcher_logged_in_uid": "",
+                "account_list": [],
+                "blocked_uid": [],
+                "INTERNAL_INFRA_THEME": "THREE_NEUTRAL_GRAY",
+                "layered_homepage_experiment_group": "Deploy: Not in Experiment",
+                "launched_url": "",
+                "sim_phone_numbers": [],
+                "is_from_registration_reminder": False,
+            },
+        )
+        context = bloks.account_access_context(screen)
+        server = bloks.server_parameters(screen, LOGIN)
+        if not all(server.get(k) for k in ("username_text_input_id", "password_text_input_id")):
+            raise LoginFlowUnsupported("Instagram did not supply login input identifiers.")
+        server.update(self._options.server_parameters)
+        oauth_server: dict[str, Any] = {
+            key: server[key]
+            for key in (
+                "is_from_logged_out",
+                "layered_homepage_experiment_group",
+                "device_id",
+                "login_surface",
+                "waterfall_id",
+                "is_platform_login",
+                "login_entry_point",
+                "family_device_id",
+                "offline_experiment_group",
+                "access_flow_version",
+                "is_from_logged_in_switcher",
+                "qe_device_id",
+            )
+            if key in server
+        }
+        self._latency(oauth_server)
+        await self._action(
+            OAUTH,
+            {
+                "client_input_params": {
+                    "username_input": username,
+                    "aac": context,
+                    "lois_settings": {"lois_token": ""},
+                    "cloud_trust_token": None,
+                    "zero_balance_state": "",
+                    "si_device_param_network_info": self._network_info(),
+                },
+                "server_params": oauth_server,
+            },
+        )
+        bootstrap = await self._transport.send("GET", "qe/sync/")
+        if bootstrap.status_code not in {200, 405}:
+            bootstrap.raise_for_error(bootstrap.json())
+        try:
+            key = PasswordKey(
+                int(bootstrap.headers["ig-set-password-encryption-key-id"]),
+                bootstrap.headers["ig-set-password-encryption-pub-key"],
+            )
+        except (KeyError, ValueError):
+            raise ProtocolError(
+                "Instagram did not supply valid password encryption keys."
+            ) from None
+        client: dict[str, Any] = {
+            "blocked_uids": [],
+            "aac": context,
+            "sim_phones": [],
+            "aymh_accounts": [],
+            "secure_family_device_id": "",
+            "has_granted_read_contacts_permissions": 0,
+            "auth_secure_device_id": "",
+            "has_whatsapp_installed": 0,
+            "si_device_param_network_info": self._network_info(),
+            "password": key.encrypt(password),
+            "sso_token_map_json_string": "",
+            "block_store_machine_id": "",
+            "ig_vetted_device_nonces": None,
+            "cloud_trust_token": None,
+            "event_flow": "login_manual",
+            "password_contains_non_ascii": str(not password.isascii()).lower(),
+            "client_known_key_hash": "",
+            "sso_accounts_auth_data": [],
+            "encrypted_msisdn": "",
+            "has_granted_read_phone_permissions": 0,
+            "app_manager_id": "",
+            "should_show_nested_nta_from_aymh": 0,
+            "device_id": device.android_id,
+            "zero_balance_state": "",
+            "login_attempt_count": 1,
+            "machine_id": session.mid or "",
+            "flash_call_permission_status": dict.fromkeys(
+                ("READ_PHONE_STATE", "READ_CALL_LOG", "ANSWER_PHONE_CALLS"), "DENIED"
+            ),
+            "accounts_list": [],
+            "gms_incoming_call_retriever_eligibility": "not_eligible",
+            "family_device_id": device.family_id,
+            "fb_ig_device_id": [],
+            "device_emails": [],
+            "try_num": 1,
+            "lois_settings": {"lois_token": ""},
+            "event_step": "home_page",
+            "headers_infra_flow_id": "",
+            "openid_tokens": {},
+            "contact_point": username,
+        }
+        client.update(self._options.client_parameters)
+        self._latency(server)
+        server["is_from_empty_password"] = 0
+        # The captured emulator reports unavailable Android keystore (-1013). Python also
+        # lacks that keystore; no certificate, signed nonce, or hardware claim is fabricated.
+        attest = json.dumps(
+            {
+                "attestation": [
+                    {
+                        "version": 2,
+                        "type": "keystore",
+                        "errors": [-1013],
+                        "challenge_nonce": challenge_nonce,
+                        "signed_nonce": "",
+                        "key_hash": "",
+                    }
+                ]
+            },
+            separators=(",", ":"),
+        )
+        payload = await self._action(
+            LOGIN,
+            {"client_input_params": client, "server_params": server},
+            {"X-IG-Attest-Params": attest},
+        )
+        parsed = bloks.login_result(payload)
+        # Embedded CAA headers are JSON values; the live key-id header can be an integer.
+        # Normalize scalar values before handing them to HTTPX's wire-header container.
+        if any(
+            not isinstance(k, str) or type(v) not in (str, int)
+            for k, v in parsed["headers"].items()
+        ):
+            raise ProtocolError("Instagram returned an unsupported embedded header value.")
+        try:
+            headers = httpx.Headers({k: str(v) for k, v in parsed["headers"].items()})
+        except (ValueError, UnicodeError):
+            raise ProtocolError("Instagram returned an invalid embedded header.") from None
+        self._transport.receive_state(headers)
+        return APIResponse(
+            200, headers, self._endpoint(LOGIN), json.dumps(parsed["result"]).encode()
+        )
+
+    async def _action(
+        self, name: str, params: dict[str, Any], headers: dict[str, str] | None = None
+    ) -> dict[str, Any]:
+        version = self._transport.session.profile.bloks_version
+        if name == PREPARE:
+            params = {**params, **self._options.prepare_parameters}
+        form = {
+            "params": json.dumps(params, separators=(",", ":")),
+            "bloks_versioning_id": version,
+            "bk_client_context": json.dumps(
+                {
+                    "bloks_version": version,
+                    "styles_id": self._options.styles_id,
+                    "theme_params": [
+                        {
+                            "value": [self._options.theme],
+                            "design_system_name": self._options.design_system,
+                        }
+                    ],
+                },
+                separators=(",", ":"),
+            ),
+        }
+        response = await self._transport.send(
+            "POST", self._endpoint(name), RequestData(form, headers or {})
+        )
+        result = response.json()
+        response.raise_for_error(result)
+        return result
+
+    @staticmethod
+    def _endpoint(name: str) -> str:
+        return f"bloks/async_action/{name}/"
+
+    def _latency(self, params: dict[str, Any]) -> None:
+        params["INTERNAL__latency_qpl_marker_id"] = self._options.latency_marker_id
+        params["INTERNAL__latency_qpl_instance_id"] = int(time.time() * 1000)
+
+    def _network_info(self) -> dict[str, Any]:
+        if self._options.network_info is not None:
+            return self._options.network_info
+        # A Python process has no Android telephony subscriptions to report.
+        return {
+            "active_subscriptions_info": None,
+            "default_subscription_info": None,
+            "active_data_subscription_info": None,
+            "default_sms_subscription_info": None,
+            "is_airplane_mode": 0,
+            "is_active_network_cellular": 0,
+            "is_device_sms_capable": 0,
+            "sim_count": 0,
+            "is_wifi": 1,
+        }