ip2vn 1.0.0__tar.gz

ip2vn-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IP2.VN
+
+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.

ip2vn-1.0.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: ip2vn
+Version: 1.0.0
+Summary: SDK chính thức của IP2.VN — điều khiển proxy xoay IP dân cư Viettel cho bên làm tool tích hợp.
+Author: IP2.VN
+License: MIT
+Project-URL: Homepage, https://ip2.vn
+Keywords: ip2,ip2vn,proxy,rotating-proxy,residential-proxy,viettel,sdk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: Proxy Servers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ip2vn
+
+SDK Python chính thức của [IP2.VN](https://ip2.vn) — điều khiển proxy xoay IP dân
+cư Viettel cho bên làm tool tích hợp. Không phụ thuộc thư viện ngoài (chỉ dùng
+`urllib` chuẩn), cần Python 3.8+.
+
+```bash
+pip install ip2vn
+```
+
+## Mô hình giới thiệu (hoa hồng 10%)
+
+Tool của bạn nhúng **mã giới thiệu công khai** của bạn và đưa người dùng đăng ký
+qua `IP2.ref_link('MÃ')`. Người dùng tự mua proxy, tự tạo **key theo từng cổng**
+rồi dán vào tool; bạn ăn 10% chi tiêu của họ.
+
+> **An toàn:** chỉ nhúng mã giới thiệu (công khai). TUYỆT ĐỐI không nhúng key,
+> mật khẩu hay token vào tool phát đi — tool nào cũng bung xem được. Key là của
+> chính người dùng cuối, không phải của bạn.
+
+## Dùng
+
+```python
+from ip2vn import IP2, IP2Error
+
+# Link đưa cho người dùng để họ gắn với bạn:
+print(IP2.ref_link("MÃ_GIỚI_THIỆU_CỦA_BẠN"))   # https://ip2.vn/?ref=...
+
+# Người dùng dán key cổng của họ vào tool của bạn:
+cong = IP2("ip2_xxxxxxxxxxxx")
+
+tin = cong.info()        # host, port, ip, cooldown, expire_at, ...
+kq  = cong.rotate()      # { ip, previous_ip, took, next_allowed_in }
+cong.auto(300)           # hẹn tự xoay mỗi 300s (0 để tắt, thấp nhất 180)
+ls  = cong.history(limit=20)
+cong.renew(30)           # gia hạn 1/7/30 ngày, trừ ví người dùng
+
+# Chuỗi proxy sẵn dùng (user/pass proxy do người dùng nhập):
+px = cong.proxy("u", "p")
+print(px["url"])   # http://u:p@host:port
+print(px["tho"])   # host:port:u:p
+
+try:
+    cong.rotate()
+except IP2Error as e:
+    print(e.code, e.message, e.retry_after)
+```
+
+## Phương thức
+
+| Gọi | Trả về |
+|---|---|
+| `info()` | host, port, line, ip, protocol, auto, cooldown, expire_at, rotations |
+| `rotate(wait=True)` | ip, previous_ip, took, next_allowed_in |
+| `auto(giây)` | auto, every, next_at |
+| `history(limit, since)` | total, items[{ip, at}] |
+| `renew(1\|7\|30)` | days_added, charged, wallet_balance, expire_at |
+| `proxy(username, password, protocol)` | host, port, url, tho |
+| `IP2.ref_link(mã)` | `https://ip2.vn/?ref=mã` |
+
+Lỗi ném ra `IP2Error` với `.code` (máy đọc), `.message` (tiếng Việt), `.status`
+(HTTP), `.retry_after` (giây, khi dính `cooldown`).
+
+Cổng nghe cả HTTP lẫn SOCKS5 trên cùng một port — chọn giao thức chỉ đổi cách
+viết chuỗi, không đổi port.
+
+MIT © IP2.VN

ip2vn-1.0.0/README.md

@@ -0,0 +1,67 @@
+# ip2vn
+
+SDK Python chính thức của [IP2.VN](https://ip2.vn) — điều khiển proxy xoay IP dân
+cư Viettel cho bên làm tool tích hợp. Không phụ thuộc thư viện ngoài (chỉ dùng
+`urllib` chuẩn), cần Python 3.8+.
+
+```bash
+pip install ip2vn
+```
+
+## Mô hình giới thiệu (hoa hồng 10%)
+
+Tool của bạn nhúng **mã giới thiệu công khai** của bạn và đưa người dùng đăng ký
+qua `IP2.ref_link('MÃ')`. Người dùng tự mua proxy, tự tạo **key theo từng cổng**
+rồi dán vào tool; bạn ăn 10% chi tiêu của họ.
+
+> **An toàn:** chỉ nhúng mã giới thiệu (công khai). TUYỆT ĐỐI không nhúng key,
+> mật khẩu hay token vào tool phát đi — tool nào cũng bung xem được. Key là của
+> chính người dùng cuối, không phải của bạn.
+
+## Dùng
+
+```python
+from ip2vn import IP2, IP2Error
+
+# Link đưa cho người dùng để họ gắn với bạn:
+print(IP2.ref_link("MÃ_GIỚI_THIỆU_CỦA_BẠN"))   # https://ip2.vn/?ref=...
+
+# Người dùng dán key cổng của họ vào tool của bạn:
+cong = IP2("ip2_xxxxxxxxxxxx")
+
+tin = cong.info()        # host, port, ip, cooldown, expire_at, ...
+kq  = cong.rotate()      # { ip, previous_ip, took, next_allowed_in }
+cong.auto(300)           # hẹn tự xoay mỗi 300s (0 để tắt, thấp nhất 180)
+ls  = cong.history(limit=20)
+cong.renew(30)           # gia hạn 1/7/30 ngày, trừ ví người dùng
+
+# Chuỗi proxy sẵn dùng (user/pass proxy do người dùng nhập):
+px = cong.proxy("u", "p")
+print(px["url"])   # http://u:p@host:port
+print(px["tho"])   # host:port:u:p
+
+try:
+    cong.rotate()
+except IP2Error as e:
+    print(e.code, e.message, e.retry_after)
+```
+
+## Phương thức
+
+| Gọi | Trả về |
+|---|---|
+| `info()` | host, port, line, ip, protocol, auto, cooldown, expire_at, rotations |
+| `rotate(wait=True)` | ip, previous_ip, took, next_allowed_in |
+| `auto(giây)` | auto, every, next_at |
+| `history(limit, since)` | total, items[{ip, at}] |
+| `renew(1\|7\|30)` | days_added, charged, wallet_balance, expire_at |
+| `proxy(username, password, protocol)` | host, port, url, tho |
+| `IP2.ref_link(mã)` | `https://ip2.vn/?ref=mã` |
+
+Lỗi ném ra `IP2Error` với `.code` (máy đọc), `.message` (tiếng Việt), `.status`
+(HTTP), `.retry_after` (giây, khi dính `cooldown`).
+
+Cổng nghe cả HTTP lẫn SOCKS5 trên cùng một port — chọn giao thức chỉ đổi cách
+viết chuỗi, không đổi port.
+
+MIT © IP2.VN

ip2vn-1.0.0/ip2vn.egg-info/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: ip2vn
+Version: 1.0.0
+Summary: SDK chính thức của IP2.VN — điều khiển proxy xoay IP dân cư Viettel cho bên làm tool tích hợp.
+Author: IP2.VN
+License: MIT
+Project-URL: Homepage, https://ip2.vn
+Keywords: ip2,ip2vn,proxy,rotating-proxy,residential-proxy,viettel,sdk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: Proxy Servers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ip2vn
+
+SDK Python chính thức của [IP2.VN](https://ip2.vn) — điều khiển proxy xoay IP dân
+cư Viettel cho bên làm tool tích hợp. Không phụ thuộc thư viện ngoài (chỉ dùng
+`urllib` chuẩn), cần Python 3.8+.
+
+```bash
+pip install ip2vn
+```
+
+## Mô hình giới thiệu (hoa hồng 10%)
+
+Tool của bạn nhúng **mã giới thiệu công khai** của bạn và đưa người dùng đăng ký
+qua `IP2.ref_link('MÃ')`. Người dùng tự mua proxy, tự tạo **key theo từng cổng**
+rồi dán vào tool; bạn ăn 10% chi tiêu của họ.
+
+> **An toàn:** chỉ nhúng mã giới thiệu (công khai). TUYỆT ĐỐI không nhúng key,
+> mật khẩu hay token vào tool phát đi — tool nào cũng bung xem được. Key là của
+> chính người dùng cuối, không phải của bạn.
+
+## Dùng
+
+```python
+from ip2vn import IP2, IP2Error
+
+# Link đưa cho người dùng để họ gắn với bạn:
+print(IP2.ref_link("MÃ_GIỚI_THIỆU_CỦA_BẠN"))   # https://ip2.vn/?ref=...
+
+# Người dùng dán key cổng của họ vào tool của bạn:
+cong = IP2("ip2_xxxxxxxxxxxx")
+
+tin = cong.info()        # host, port, ip, cooldown, expire_at, ...
+kq  = cong.rotate()      # { ip, previous_ip, took, next_allowed_in }
+cong.auto(300)           # hẹn tự xoay mỗi 300s (0 để tắt, thấp nhất 180)
+ls  = cong.history(limit=20)
+cong.renew(30)           # gia hạn 1/7/30 ngày, trừ ví người dùng
+
+# Chuỗi proxy sẵn dùng (user/pass proxy do người dùng nhập):
+px = cong.proxy("u", "p")
+print(px["url"])   # http://u:p@host:port
+print(px["tho"])   # host:port:u:p
+
+try:
+    cong.rotate()
+except IP2Error as e:
+    print(e.code, e.message, e.retry_after)
+```
+
+## Phương thức
+
+| Gọi | Trả về |
+|---|---|
+| `info()` | host, port, line, ip, protocol, auto, cooldown, expire_at, rotations |
+| `rotate(wait=True)` | ip, previous_ip, took, next_allowed_in |
+| `auto(giây)` | auto, every, next_at |
+| `history(limit, since)` | total, items[{ip, at}] |
+| `renew(1\|7\|30)` | days_added, charged, wallet_balance, expire_at |
+| `proxy(username, password, protocol)` | host, port, url, tho |
+| `IP2.ref_link(mã)` | `https://ip2.vn/?ref=mã` |
+
+Lỗi ném ra `IP2Error` với `.code` (máy đọc), `.message` (tiếng Việt), `.status`
+(HTTP), `.retry_after` (giây, khi dính `cooldown`).
+
+Cổng nghe cả HTTP lẫn SOCKS5 trên cùng một port — chọn giao thức chỉ đổi cách
+viết chuỗi, không đổi port.
+
+MIT © IP2.VN

ip2vn-1.0.0/ip2vn.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+LICENSE
+README.md
+ip2vn.py
+pyproject.toml
+ip2vn.egg-info/PKG-INFO
+ip2vn.egg-info/SOURCES.txt
+ip2vn.egg-info/dependency_links.txt
+ip2vn.egg-info/top_level.txt

ip2vn-1.0.0/ip2vn.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ip2vn-1.0.0/ip2vn.egg-info/top_level.txt

@@ -0,0 +1 @@
+ip2vn

ip2vn-1.0.0/ip2vn.py

@@ -0,0 +1,151 @@
+"""SDK Python chính thức cho IP2.VN — dành cho bên làm tool tích hợp proxy.
+
+Mô hình GIỚI THIỆU: tool của bạn nhúng MÃ GIỚI THIỆU CÔNG KHAI của bạn và đẩy
+người dùng đăng ký qua ``IP2.ref_link(ma)``. Người dùng tự mua proxy của IP2.VN,
+bạn ăn hoa hồng giới thiệu trên chi tiêu của họ. Tool điều khiển cổng bằng KEY
+CỦA CHÍNH NGƯỜI DÙNG (họ tự tạo trong bảng điều khiển rồi dán vào tool).
+
+── AN TOÀN, đọc kỹ ──
+* Chỉ nhúng MÃ GIỚI THIỆU (công khai) vào tool phát đi. TUYỆT ĐỐI không nhúng
+  key, mật khẩu, hay token tài khoản — tool phát ra ngoài là ai cũng bung xem
+  được, nhúng bí mật vào là lộ.
+* Key ở đây là key THEO TỪNG CỔNG của người dùng cuối, không phải của bạn.
+* "Tool chỉ chạy khi có key hợp lệ" là chuyện proxy tự lo ở máy chủ: không có
+  cổng đã trả tiền thì proxy trả 407.
+
+Không phụ thuộc thư viện ngoài (chỉ dùng thư viện chuẩn urllib). Cần Python 3.8+.
+"""
+
+import json
+import urllib.request
+import urllib.parse
+import urllib.error
+
+GOC_API = "https://api.ip2.vn"
+GOC_WEB = "https://ip2.vn"
+
+
+class IP2Error(Exception):
+    """Lỗi từ API IP2.VN.
+
+    code: mã máy đọc ('cooldown', 'expired', 'invalid_key'...).
+    message: câu tiếng Việt cho người. status: mã HTTP. retry_after: giây chờ.
+    """
+
+    def __init__(self, code, message=None, status=0, retry_after=None):
+        super().__init__(message or code)
+        self.code = code
+        self.message = message or code
+        self.status = status
+        self.retry_after = retry_after
+
+
+class IP2:
+    """Điều khiển MỘT cổng proxy bằng key của cổng đó.
+
+        cong = IP2("ip2_xxxxxxxxxxxx")
+        tin = cong.info()
+        cong.rotate()
+    """
+
+    def __init__(self, key, base=GOC_API, timeout=35):
+        if not key or not isinstance(key, str):
+            raise IP2Error("missing_key", "Thiếu key của cổng.", 0)
+        self.key = key
+        self.base = base.rstrip("/")
+        self.timeout = timeout  # rotate chờ IP mới có thể tới ~30s
+
+    def _goi(self, duong, method="GET", query=None, body=None):
+        url = self.base + duong
+        if query:
+            q = {k: v for k, v in query.items() if v is not None}
+            if q:
+                url += "?" + urllib.parse.urlencode(q)
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        # User-Agent thật: mặc định của urllib giống bot, Cloudflare chặn 403.
+        headers = {"X-IP2-Key": self.key,
+                   "User-Agent": "ip2-sdk-python/1.0 (+https://ip2.vn)"}
+        if data is not None:
+            headers["content-type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                return json.loads(r.read().decode("utf-8") or "{}")
+        except urllib.error.HTTPError as e:
+            try:
+                j = json.loads(e.read().decode("utf-8") or "{}")
+            except Exception:
+                j = {}
+            ra = j.get("retry_after")
+            raise IP2Error(j.get("error", "http_%d" % e.code),
+                           j.get("message", "Lỗi không rõ."), e.code,
+                           ra if isinstance(ra, (int, float)) else None)
+        except urllib.error.URLError as e:
+            reason = getattr(e, "reason", "")
+            aborted = isinstance(reason, TimeoutError) or "timed out" in str(reason)
+            raise IP2Error("timeout" if aborted else "network_error",
+                           "Quá hạn chờ máy chủ." if aborted
+                           else "Không gọi được máy chủ IP2.VN.", 0)
+
+    def info(self):
+        """Thông tin cổng: host, port, ip hiện tại, hẹn xoay, cooldown, hạn dùng."""
+        return self._goi("/v1/info")
+
+    def rotate(self, wait=True):
+        """Xin IP mới. wait=True (mặc định) chờ tới khi có IP mới.
+
+        Trả về dict { ip, previous_ip, port, took, next_allowed_in }.
+        """
+        return self._goi("/v1/rotate", query={"wait": "true" if wait else "false"})
+
+    def auto(self, every):
+        """Hẹn giờ tự xoay. every = số giây (thấp nhất 180), 0 để tắt.
+
+        Trả về { auto, every, next_at }.
+        """
+        return self._goi("/v1/auto", method="POST", body={"every": every})
+
+    def history(self, limit=None, since=None):
+        """Lịch sử IP của cổng, mới nhất trước. since theo ISO 8601.
+
+        Trả về { total, items: [{ ip, at }] }.
+        """
+        return self._goi("/v1/history", query={"limit": limit, "since": since})
+
+    def renew(self, days):
+        """Gia hạn cổng, trừ ví chính của người dùng. days chỉ nhận 1, 7 hoặc 30.
+
+        Ví không đủ thì ném IP2Error code 'insufficient_funds' (HTTP 402), không
+        trừ gì. Trả về { days_added, charged, wallet_balance, expire_at }.
+        """
+        return self._goi("/v1/renew", method="POST", body={"days": days})
+
+    def proxy(self, username, password, protocol="http"):
+        """Dựng chuỗi proxy sẵn dùng từ host/port của cổng cộng tài khoản proxy.
+
+        LƯU Ý: user/pass proxy KHÔNG lấy từ API (bí mật của người dùng, máy chủ
+        không trả ra) — người dùng tự nhập. Host và port thì SDK đọc từ info().
+
+        Trả về dict { host, port, url, tho } — url dạng đầy đủ, tho dạng
+        host:port:user:pass.
+        """
+        t = self.info()
+        host, port = t["host"], t["port"]
+        u = urllib.parse.quote(username, safe="")
+        p = urllib.parse.quote(password, safe="")
+        return {
+            "host": host,
+            "port": port,
+            "url": "%s://%s:%s@%s:%s" % (protocol, u, p, host, port),
+            "tho": "%s:%s:%s:%s" % (host, port, username, password),
+        }
+
+    @staticmethod
+    def ref_link(ref_code, base=GOC_WEB):
+        """Link đăng ký kèm mã giới thiệu của bạn.
+
+            IP2.ref_link("ABC123")  ->  https://ip2.vn/?ref=ABC123
+        """
+        if not ref_code:
+            raise IP2Error("missing_ref", "Thiếu mã giới thiệu.", 0)
+        return "%s/?ref=%s" % (base.rstrip("/"), urllib.parse.quote(ref_code, safe=""))

ip2vn-1.0.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ip2vn"
+version = "1.0.0"
+description = "SDK chính thức của IP2.VN — điều khiển proxy xoay IP dân cư Viettel cho bên làm tool tích hợp."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "IP2.VN" }]
+keywords = ["ip2", "ip2vn", "proxy", "rotating-proxy", "residential-proxy", "viettel", "sdk"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Internet :: Proxy Servers",
+]
+
+[project.urls]
+Homepage = "https://ip2.vn"
+
+[tool.setuptools]
+py-modules = ["ip2vn"]

ip2vn-1.0.0/setup.cfg

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