hiinsta 0.1.0__tar.gz

hiinsta-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tomas Santana
+
+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.

hiinsta-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: hiinsta
+Version: 0.1.0
+Summary: A wrapper for Instagram's API
+Home-page: https://github.com/yourusername/hiinsta
+Author: Your Name
+Author-email: Tomas Santana <tomas@cervant.chat>
+License: MIT
+Project-URL: Homepage, https://github.com/cervant-ai/hiinsta
+Project-URL: Repository, https://github.com/cervant-ai/hiinsta.git
+Project-URL: Issues, https://github.com/cervant-ai/hiinsta/issues
+Keywords: hiinsta,python,package
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: requests>=2.25.1
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.8.0; extra == "dev"
+Requires-Dist: mypy>=0.800; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# hiinsta
+
+A Python package for interacting with Instagram's messaging API.
+
+## Installation
+
+```bash
+pip install hiinsta
+```
+
+## Usage
+
+```python
+from hiinsta import InstagramMessenger
+
+messenger = InstagramMessenger(access_token="YOUR_ACCESS_TOKEN")
+
+# Example usage
+message_id = await messenger.send_text("Hello, World!", recipient_id="RECIPIENT_ID")
+
+print(message_id)
+```
+
+## Development
+
+To install in development mode:
+
+```bash
+git clone https://github.com/cervant-ai/hiinsta.git
+cd hiinsta
+pip install -e .
+```
+
+To install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

hiinsta-0.1.0/README.md

@@ -0,0 +1,58 @@
+# hiinsta
+
+A Python package for interacting with Instagram's messaging API.
+
+## Installation
+
+```bash
+pip install hiinsta
+```
+
+## Usage
+
+```python
+from hiinsta import InstagramMessenger
+
+messenger = InstagramMessenger(access_token="YOUR_ACCESS_TOKEN")
+
+# Example usage
+message_id = await messenger.send_text("Hello, World!", recipient_id="RECIPIENT_ID")
+
+print(message_id)
+```
+
+## Development
+
+To install in development mode:
+
+```bash
+git clone https://github.com/cervant-ai/hiinsta.git
+cd hiinsta
+pip install -e .
+```
+
+To install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

hiinsta-0.1.0/hiinsta/InstagramMessenger.py

@@ -0,0 +1,171 @@
+import httpx
+from typing import Optional, Any, Dict
+from hiinsta.types import InstagramPayload
+from hiinsta.types.exeptions import InstagramApiException
+
+INSTAGRAM_BASE_URL = "https://graph.instagram.com"
+INSTAGRAM_MESSAGES_ENDPOINT = "/me/messages"
+DEFAULT_TIMEOUT = 15.0  # seconds
+
+class InstagramMessenger:
+    """
+    A class to interact with Instagram's messaging API.
+    """
+    access_token: str
+    request_timeout: Optional[float] = DEFAULT_TIMEOUT
+    
+    def __init__(self, access_token: str, request_timeout: Optional[float] = DEFAULT_TIMEOUT):
+        self.access_token = access_token
+        self.request_timeout = request_timeout
+
+    async def send_text(self, text: str, recipient_id: str) -> str:
+        """
+        Send a text message to a user.
+        Args:
+            text (str): The text message to send.
+            recipient_id (str): The recipient's Instagram user ID.
+        Returns:
+            str: The message ID of the sent message.
+        """
+        url = f"{INSTAGRAM_BASE_URL}{INSTAGRAM_MESSAGES_ENDPOINT}"
+        payload = {
+            "recipient": {
+                "id": recipient_id
+            },
+            "message": {
+                "text": text
+            }
+        }
+        return await self._send_message_payload(payload)
+        
+    async def send_image(self, image_url: str, recipient_id: str) -> str:
+        """
+        Send an image or GIF to a user.
+        Args:
+            image_url (str): The URL of the image or GIF to send.
+            recipient_id (str): The recipient's Instagram user ID.
+        Returns:
+            str: The message ID of the sent message.
+        """
+        return await self._send_attachment("image", image_url, recipient_id)
+    
+    async def send_video(self, video_url: str, recipient_id: str) -> str:
+        """
+        Send a video to a user.
+        Args:
+            video_url (str): The URL of the video to send.
+            recipient_id (str): The recipient's Instagram user ID.
+        Returns:
+            str: The message ID of the sent message.
+        """
+        return await self._send_attachment("video", video_url, recipient_id)
+    
+    async def send_audio(self, audio_url: str, recipient_id: str):
+        """
+        Send an audio file to a user.
+        Args:
+            audio_url (str): The URL of the audio file to send.
+            recipient_id (str): The recipient's Instagram user ID.
+        Returns:
+            str: The message ID of the sent message.
+        """
+        return await self._send_attachment("audio", audio_url, recipient_id)
+        
+    async def _send_attachment(self, attachment_type: str, attachment_url: str, recipient_id: str):
+        """
+        Send an attachment (image, video, audio, file) to a user.
+        Args:
+            attachment_type (str): The type of attachment ('image', 'video', 'audio', 'file').
+            attachment_url (str): The URL of the attachment to send.
+            recipient_id (str): The recipient's Instagram user ID.
+        """
+        payload = {
+            "recipient": {
+                "id": recipient_id
+            },
+            "message": {
+                "attachment": {
+                    "type": attachment_type,
+                    "payload": {
+                        "url": attachment_url
+                    }
+                }
+            }
+        }
+        return await self._send_message_payload(payload)
+
+    async def _send_message_payload(self, payload: dict) -> str:
+        """
+        Send a custom payload to Instagram's API messages endpoint with robust error handling.
+
+        Args:
+            payload (dict): The payload to send.
+            timeout (Optional[float]): Request timeout in seconds. Defaults to DEFAULT_TIMEOUT.
+
+        Returns:
+            SendResponse: A mapping with at least the "message_id" and, when available, "recipient_id".
+
+        Raises:
+            InstagramApiException: For network errors, non-2xx responses, or malformed responses.
+        """
+        url = f"{INSTAGRAM_BASE_URL}{INSTAGRAM_MESSAGES_ENDPOINT}"
+        headers = {
+            "Authorization": f"Bearer {self.access_token}",
+            "Content-Type": "application/json",
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=self.request_timeout) as client:
+                response = await client.post(url, json=payload, headers=headers)
+        except httpx.RequestError as e:
+            raise InstagramApiException(
+                message="Network error while sending payload",
+                endpoint=url,
+                method="POST",
+                payload=payload,
+                details=str(e),
+            ) from e
+
+        # Non-2xx -> raise a structured exception with parsed error body when possible
+        if response.status_code < 200 or response.status_code >= 300:
+            raise InstagramApiException.from_httpx_response(
+                response,
+                endpoint=url,
+                method="POST",
+                payload=payload,
+            )
+
+        # Parse JSON and validate presence of message_id
+        try:
+            data: Dict[str, Any] = response.json()
+        except ValueError:
+            raise InstagramApiException(
+                message="Response is not valid JSON",
+                endpoint=url,
+                method="POST",
+                payload=payload,
+                status_code=response.status_code,
+                response_text=response.text,
+            )
+
+        message_id = data.get("message_id") or data.get("id")
+        if not message_id:
+            raise InstagramApiException(
+                message="Missing message_id in successful response",
+                endpoint=url,
+                method="POST",
+                payload=payload,
+                status_code=response.status_code,
+                response_json=data,
+            )
+
+        
+        return message_id
+        
+    @staticmethod
+    def process_payload(payload: dict) -> InstagramPayload:
+        try:
+            return InstagramPayload(**payload)
+        except Exception as e:
+            raise ValueError(f"Invalid payload: {e}")
+        

hiinsta-0.1.0/hiinsta/__init__.py

@@ -0,0 +1,11 @@
+"""
+hiinsta - A Python package for hiinsta functionality.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Tomas Santana"
+__email__ = "tomas@cervant.chat"
+
+from .InstagramMessenger import InstagramMessenger
+
+__all__ = ["InstagramMessenger"]

hiinsta-0.1.0/hiinsta/types/__init__.py

@@ -0,0 +1,81 @@
+from pydantic import BaseModel, Field
+
+from typing import List, Optional, Dict, TypedDict
+
+
+class AttachmentPayload(BaseModel):
+    url: str
+
+
+class Attachment(BaseModel):
+    type: str
+    payload: AttachmentPayload
+
+
+class QuickReply(BaseModel):
+    payload: str
+
+
+class AdsContextData(BaseModel):
+    ad_title: str
+    photo_url: str
+    video_url: str
+
+
+class Referral(BaseModel):
+    ref: Optional[str]
+    ad_id: Optional[str]
+    source: Optional[str]
+    type: Optional[str]
+    ads_context_data: Optional[AdsContextData]
+
+
+class ReplyToStory(BaseModel):
+    url: str
+    id: str
+
+
+class ReplyTo(BaseModel):
+    mid: Optional[str]
+    story: Optional[ReplyToStory]
+
+
+class Message(BaseModel):
+    mid: str
+    attachments: Optional[List[Attachment]] = None
+    is_deleted: Optional[bool] = None
+    is_echo: bool = Field(default=False)
+    is_unsupported: Optional[bool] = None
+    quick_reply: Optional[QuickReply] = None
+    referral: Optional[Referral] = None
+    reply_to: Optional[ReplyTo] = None
+    text: Optional[str] = None
+
+
+class Messaging(BaseModel):
+    sender: Dict[str, str]
+    recipient: Dict[str, str]
+    timestamp: int
+    message: Message
+
+
+class Entry(BaseModel):
+    id: str
+    time: int
+    messaging: List[Messaging]
+
+class InstagramPayload(BaseModel):
+    object: str
+    entry: List[Entry]
+
+class InstagramUser(BaseModel):
+    id: str
+    username: str
+    name: str
+    
+class SendResponse(TypedDict):
+    recipient_id: str
+    message_id: str
+
+
+

hiinsta-0.1.0/hiinsta/types/exeptions/InstagramApiExeption.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class InstagramApiException(Exception):
+	"""Exception raised for Instagram API errors.
+
+	Captures HTTP details, endpoint, method, payload, and parsed error body when available.
+	"""
+
+	def __init__(
+		self,
+		message: str,
+		*,
+		status_code: Optional[int] = None,
+		endpoint: Optional[str] = None,
+		method: Optional[str] = None,
+		payload: Optional[Dict[str, Any]] = None,
+		response_text: Optional[str] = None,
+		response_json: Optional[Dict[str, Any]] = None,
+		details: Optional[str] = None,
+		error_code: Optional[str] = None,
+	) -> None:
+		super().__init__(message)
+		self.message = message
+		self.status_code = status_code
+		self.endpoint = endpoint
+		self.method = method
+		self.payload = payload
+		self.response_text = response_text
+		self.response_json = response_json
+		self.details = details
+		self.error_code = error_code
+
+	def __str__(self) -> str:
+		base = self.message
+		parts = []
+		if self.status_code is not None:
+			parts.append(f"status={self.status_code}")
+		if self.endpoint:
+			parts.append(f"endpoint={self.endpoint}")
+		if self.method:
+			parts.append(f"method={self.method}")
+		if self.error_code:
+			parts.append(f"error_code={self.error_code}")
+		if self.details:
+			parts.append(f"details={self.details}")
+		if parts:
+			base += " (" + ", ".join(parts) + ")"
+		return base
+
+	@classmethod
+	def from_httpx_response(
+		cls,
+		response: Any,
+		*,
+		endpoint: Optional[str] = None,
+		method: Optional[str] = None,
+		payload: Optional[Dict[str, Any]] = None,
+	) -> "InstagramApiException":
+		"""
+		Build an exception from an httpx.Response, attempting to parse JSON error details.
+		"""
+		status = getattr(response, "status_code", None)
+		text = None
+		data: Optional[Dict[str, Any]] = None
+		code: Optional[str] = None
+		message: str = "Instagram API request failed"
+
+		try:
+			data = response.json()
+			# Graph API errors are often under { "error": { "message": "...", "code": 190, ... } }
+			err = data.get("error") if isinstance(data, dict) else None
+			if isinstance(err, dict):
+				message = err.get("message") or message
+				code_value = err.get("code")
+				code = str(code_value) if code_value is not None else None
+		except Exception:
+			text = getattr(response, "text", None)
+
+		return cls(
+			message=message,
+			status_code=status,
+			endpoint=endpoint,
+			method=method,
+			payload=payload,
+			response_text=text,
+			response_json=data,
+			error_code=code,
+		)
+

hiinsta-0.1.0/hiinsta/types/exeptions/__init__.py

@@ -0,0 +1,4 @@
+from .InstagramApiExeption import InstagramApiException
+
+__all__ = ["InstagramApiException"]
+

hiinsta-0.1.0/hiinsta.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: hiinsta
+Version: 0.1.0
+Summary: A wrapper for Instagram's API
+Home-page: https://github.com/yourusername/hiinsta
+Author: Your Name
+Author-email: Tomas Santana <tomas@cervant.chat>
+License: MIT
+Project-URL: Homepage, https://github.com/cervant-ai/hiinsta
+Project-URL: Repository, https://github.com/cervant-ai/hiinsta.git
+Project-URL: Issues, https://github.com/cervant-ai/hiinsta/issues
+Keywords: hiinsta,python,package
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: requests>=2.25.1
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.8.0; extra == "dev"
+Requires-Dist: mypy>=0.800; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# hiinsta
+
+A Python package for interacting with Instagram's messaging API.
+
+## Installation
+
+```bash
+pip install hiinsta
+```
+
+## Usage
+
+```python
+from hiinsta import InstagramMessenger
+
+messenger = InstagramMessenger(access_token="YOUR_ACCESS_TOKEN")
+
+# Example usage
+message_id = await messenger.send_text("Hello, World!", recipient_id="RECIPIENT_ID")
+
+print(message_id)
+```
+
+## Development
+
+To install in development mode:
+
+```bash
+git clone https://github.com/cervant-ai/hiinsta.git
+cd hiinsta
+pip install -e .
+```
+
+To install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

hiinsta-0.1.0/hiinsta.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+hiinsta/InstagramMessenger.py
+hiinsta/__init__.py
+hiinsta.egg-info/PKG-INFO
+hiinsta.egg-info/SOURCES.txt
+hiinsta.egg-info/dependency_links.txt
+hiinsta.egg-info/requires.txt
+hiinsta.egg-info/top_level.txt
+hiinsta/types/__init__.py
+hiinsta/types/exeptions/InstagramApiExeption.py
+hiinsta/types/exeptions/__init__.py
+tests/__init__.py
+tests/test_core.py

hiinsta-0.1.0/hiinsta.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hiinsta-0.1.0/hiinsta.egg-info/requires.txt

@@ -0,0 +1,9 @@
+pydantic>=2.11.7
+httpx>=0.28.1
+requests>=2.25.1
+
+[dev]
+pytest>=6.0
+black>=21.0
+flake8>=3.8.0
+mypy>=0.800

hiinsta-0.1.0/hiinsta.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+hiinsta
+tests

hiinsta-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hiinsta"
+version = "0.1.0"
+description = "A wrapper for Instagram's API"
+readme = "README.md"
+requires-python = ">=3.7"
+license = {text = "MIT"}
+authors = [
+    {name = "Tomas Santana", email = "tomas@cervant.chat"},
+]
+keywords = ["hiinsta", "python", "package"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "pydantic>=2.11.7",
+    "httpx>=0.28.1",
+    "requests>=2.25.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=6.0",
+    "black>=21.0",
+    "flake8>=3.8.0",
+    "mypy>=0.800",
+]
+
+[project.urls]
+Homepage = "https://github.com/cervant-ai/hiinsta"
+Repository = "https://github.com/cervant-ai/hiinsta.git"
+Issues = "https://github.com/cervant-ai/hiinsta/issues"
+
+[tool.black]
+line-length = 88
+target-version = ['py37']
+
+[tool.mypy]
+python_version = "3.7"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

hiinsta-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hiinsta-0.1.0/setup.py

@@ -0,0 +1,41 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="hiinsta",
+    version="0.1.0",
+    author="Your Name",
+    author_email="your.email@example.com",
+    description="A Python package for hiinsta",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/yourusername/hiinsta",
+    packages=find_packages(),
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+    ],
+    python_requires=">=3.7",
+    install_requires=[
+        "pydantic>=2.11.7",
+        "httpx>=0.28.1",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=6.0",
+            "black>=21.0",
+            "flake8>=3.8.0",
+            "mypy>=0.800",
+        ],
+    },
+)

hiinsta-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+# Empty file to make tests directory a Python package

hiinsta-0.1.0/tests/test_core.py

@@ -0,0 +1 @@
+import pytest