dcoink 0.1.0__tar.gz

dcoink-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# 忽略内部规划文件，不提交到 GitHub
+roadmap.md
+API_REFERENCE.md
+
+# 常见开发环境忽略
+node_modules/
+dist/
+.env
+.DS_Store
+__pycache__/
+*.pyc

dcoink-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: dcoink
+Version: 0.1.0
+Summary: The official Python SDK for dco.ink - A minimalist and developer-friendly URL shortener
+Project-URL: Homepage, https://dco.ink
+Project-URL: Source, https://github.com/dco/dco-ink-tools
+Author-email: "dco.ink" <hello@dco.ink>
+License-Expression: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# dcoink - Official Python SDK for dco.ink
+
+The official, beautifully typed Python SDK for [dco.ink](https://dco.ink) - the minimalist, privacy-first URL shortener.
+
+## Installation
+
+```bash
+pip install dcoink
+```
+
+## Quick Start (Anonymous Mode)
+You don't even need an account to start shortening URLs! The SDK provides a blazing-fast anonymous mode.
+
+```python
+import dcoink
+
+link = dcoink.shorten("https://example.com/a-very-long-url-that-needs-shortening")
+
+print(f"Short URL: {link.short_url}")
+# Output: https://dco.ink/xyz123
+```
+
+## Authenticated Mode
+By passing your API Key, you can manage your links and access advanced features (like specifying custom short codes).
+
+```python
+import dcoink
+
+link = dcoink.shorten(
+    "https://example.com/my-campaign",
+    custom_code="mybrand",
+    api_key="dco_xxxxxx"
+)
+
+print(link.short_url)
+# Output: https://dco.ink/mybrand
+```
+
+## Advanced Usage (Client API)
+
+For robust applications, use the `Client` to manage your links, check history, and more.
+
+```python
+from dcoink import Client
+
+with Client(api_key="dco_xxxxxx") as client:
+    # Get user info
+    me = client.get_me()
+    print(f"Logged in as {me.name}")
+    
+    # Create a link
+    link = client.create_link("https://github.com", custom_code="git")
+    
+    # List history
+    links = client.list_links(limit=10)
+    for l in links:
+        print(l.short_url, l.clicks)
+        
+    # Update and delete
+    client.update_link("git", "https://github.com/new-target")
+    client.delete_link("git")
+```
+
+## Async Support
+
+Building high-concurrency scrapers or bots? We've got you covered with `AsyncClient` powered by `httpx`.
+
+```python
+import asyncio
+from dcoink import AsyncClient
+
+async def main():
+    async with AsyncClient(api_key="dco_xxxxxx") as client:
+        link = await client.create_link("https://example.com")
+        print(link.short_url)
+
+asyncio.run(main())
+```
+
+## Built-in CLI Tool
+When you install the SDK, you also get a neat terminal command!
+
+```bash
+# Quick shorten
+dcoink shorten https://example.com
+
+# Custom short code
+dcoink shorten https://example.com -c mybrand -k dco_xxxxxx
+```

dcoink-0.1.0/README.md

@@ -0,0 +1,89 @@
+# dcoink - Official Python SDK for dco.ink
+
+The official, beautifully typed Python SDK for [dco.ink](https://dco.ink) - the minimalist, privacy-first URL shortener.
+
+## Installation
+
+```bash
+pip install dcoink
+```
+
+## Quick Start (Anonymous Mode)
+You don't even need an account to start shortening URLs! The SDK provides a blazing-fast anonymous mode.
+
+```python
+import dcoink
+
+link = dcoink.shorten("https://example.com/a-very-long-url-that-needs-shortening")
+
+print(f"Short URL: {link.short_url}")
+# Output: https://dco.ink/xyz123
+```
+
+## Authenticated Mode
+By passing your API Key, you can manage your links and access advanced features (like specifying custom short codes).
+
+```python
+import dcoink
+
+link = dcoink.shorten(
+    "https://example.com/my-campaign",
+    custom_code="mybrand",
+    api_key="dco_xxxxxx"
+)
+
+print(link.short_url)
+# Output: https://dco.ink/mybrand
+```
+
+## Advanced Usage (Client API)
+
+For robust applications, use the `Client` to manage your links, check history, and more.
+
+```python
+from dcoink import Client
+
+with Client(api_key="dco_xxxxxx") as client:
+    # Get user info
+    me = client.get_me()
+    print(f"Logged in as {me.name}")
+    
+    # Create a link
+    link = client.create_link("https://github.com", custom_code="git")
+    
+    # List history
+    links = client.list_links(limit=10)
+    for l in links:
+        print(l.short_url, l.clicks)
+        
+    # Update and delete
+    client.update_link("git", "https://github.com/new-target")
+    client.delete_link("git")
+```
+
+## Async Support
+
+Building high-concurrency scrapers or bots? We've got you covered with `AsyncClient` powered by `httpx`.
+
+```python
+import asyncio
+from dcoink import AsyncClient
+
+async def main():
+    async with AsyncClient(api_key="dco_xxxxxx") as client:
+        link = await client.create_link("https://example.com")
+        print(link.short_url)
+
+asyncio.run(main())
+```
+
+## Built-in CLI Tool
+When you install the SDK, you also get a neat terminal command!
+
+```bash
+# Quick shorten
+dcoink shorten https://example.com
+
+# Custom short code
+dcoink shorten https://example.com -c mybrand -k dco_xxxxxx
+```

dcoink-0.1.0/dcoink/__init__.py

@@ -0,0 +1,52 @@
+"""
+dcoink - The official Python SDK for dco.ink
+"""
+
+import httpx
+from typing import Optional
+
+from .models import Link, UserInfo
+from .client import Client, BASE_URL
+from .async_client import AsyncClient
+from . import errors
+
+def shorten(url: str, custom_code: Optional[str] = None, api_key: Optional[str] = None, base_url: str = BASE_URL) -> Link:
+    """
+    Intelligently shortens a URL.
+    - If `api_key` is provided, calls POST /api/links (authenticated, allows custom codes).
+    - If `api_key` is NOT provided, calls GET /api/s (fast anonymous mode).
+    """
+    if custom_code and not api_key:
+        raise errors.ValidationError("custom_code requires an api_key to be provided.")
+        
+    if api_key:
+        # Authenticated Mode
+        with Client(api_key=api_key, base_url=base_url) as client:
+            return client.create_link(url, custom_code=custom_code)
+    else:
+        # Fast Anonymous Mode
+        response = httpx.get(f"{base_url}/api/s", params={"url": url})
+        
+        if not response.is_success:
+            # Handle specific known errors from the plain-text endpoint
+            if response.text.startswith("error: invalid_url"):
+                raise errors.ValidationError("Please provide a valid URL.", status_code=response.status_code)
+            raise errors.DcoApiError(f"Failed to create anonymous link: {response.text}", status_code=response.status_code)
+            
+        short_url = response.text.strip()
+        short_code = short_url.split("/")[-1]
+        
+        return Link(
+            short_code=short_code,
+            short_url=short_url,
+            target_url=url
+        )
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "Link",
+    "UserInfo",
+    "shorten",
+    "errors",
+]

dcoink-0.1.0/dcoink/async_client.py

@@ -0,0 +1,113 @@
+import httpx
+from typing import List, Optional, Dict, Any
+from .models import Link, UserInfo
+from .errors import (
+    DcoApiError,
+    AuthenticationError,
+    ValidationError,
+    CodeTakenError,
+    ForbiddenError,
+    RateLimitError
+)
+
+BASE_URL = "https://api.dco.ink"
+
+class AsyncClient:
+    """Asynchronous client for the dco.ink API."""
+    
+    def __init__(self, api_key: str, base_url: str = BASE_URL, timeout: float = 10.0):
+        self.api_key = api_key
+        self.base_url = base_url
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={
+                "X-API-Key": self.api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "dcoink-python-sdk/0.1.0"
+            },
+            timeout=timeout
+        )
+
+    def _handle_error(self, response: httpx.Response):
+        try:
+            data = response.json()
+            error_code = data.get("error", "unknown_error")
+            message = data.get("message", response.text)
+        except Exception:
+            error_code = "unknown_error"
+            message = response.text
+
+        status = response.status_code
+        if status == 401:
+            raise AuthenticationError(message, error_code, status)
+        elif status == 403:
+            raise ForbiddenError(message, error_code, status)
+        elif status == 409:
+            raise CodeTakenError(message, error_code, status)
+        elif status == 429:
+            raise RateLimitError("Rate limit exceeded", error_code, status)
+        elif status == 400:
+            raise ValidationError(message, error_code, status)
+        else:
+            raise DcoApiError(message, error_code, status)
+
+    async def _request(self, method: str, path: str, **kwargs) -> Any:
+        response = await self._client.request(method, path, **kwargs)
+        if not response.is_success:
+            self._handle_error(response)
+        
+        if response.status_code == 204 or not response.content:
+            return None
+            
+        return response.json()
+
+    async def get_me(self) -> UserInfo:
+        """Get the current authenticated user's details."""
+        data = await self._request("GET", "/api/auth/me")
+        return UserInfo.from_dict(data)
+
+    async def create_link(self, url: str, custom_code: Optional[str] = None) -> Link:
+        """Create a new shortened link."""
+        payload = {"url": url}
+        if custom_code:
+            payload["custom_code"] = custom_code
+            
+        data = await self._request("POST", "/api/links", json=payload)
+        return Link(
+            short_code=data["short_code"],
+            short_url=data["short_url"],
+            target_url=data.get("target_url", url),
+            expires_at=data.get("expires_at")
+        )
+
+    async def list_links(self, limit: int = 50, offset: int = 0) -> List[Link]:
+        """List all links created by the current user."""
+        data = await self._request("GET", "/api/links", params={"limit": limit, "offset": offset})
+        links = []
+        for item in data.get("links", []):
+            links.append(Link(
+                short_code=item["short_code"],
+                short_url=f"https://dco.ink/{item['short_code']}",
+                target_url=item.get("target_url"),
+                created_at=item.get("created_at"),
+                expires_at=item.get("expires_at")
+            ))
+        return links
+
+    async def update_link(self, short_code: str, new_url: str) -> None:
+        """Update the target URL of an existing link."""
+        await self._request("PUT", f"/api/links/{short_code}", json={"url": new_url})
+
+    async def delete_link(self, short_code: str) -> None:
+        """Delete an existing link."""
+        await self._request("DELETE", f"/api/links/{short_code}")
+
+    async def close(self):
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

dcoink-0.1.0/dcoink/cli.py

@@ -0,0 +1,34 @@
+import argparse
+import sys
+import dcoink
+
+def main():
+    parser = argparse.ArgumentParser(description="dco.ink - Minimalist URL Shortener CLI")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # shorten subcommand
+    shorten_parser = subparsers.add_parser("shorten", help="Shorten a URL")
+    shorten_parser.add_argument("url", help="The long URL to shorten")
+    shorten_parser.add_argument("-c", "--code", help="Custom short code (requires API Key)", default=None)
+    shorten_parser.add_argument("-k", "--key", help="Your dco.ink API Key (optional for random links)", default=None)
+    
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+    
+    try:
+        link = dcoink.shorten(url=args.url, custom_code=args.code, api_key=args.key)
+        print(f"✅ Success! Your short link is ready:")
+        print(f"👉 {link.short_url}")
+    except dcoink.errors.DcoApiError as e:
+        print(f"❌ API Error: {e.message}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"❌ Unexpected Error: {str(e)}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()
+

dcoink-0.1.0/dcoink/client.py

@@ -0,0 +1,114 @@
+import httpx
+from typing import List, Optional, Dict, Any
+from .models import Link, UserInfo
+from .errors import (
+    DcoApiError,
+    AuthenticationError,
+    ValidationError,
+    CodeTakenError,
+    ForbiddenError,
+    RateLimitError
+)
+
+BASE_URL = "https://api.dco.ink"
+
+class Client:
+    """Synchronous client for the dco.ink API."""
+    
+    def __init__(self, api_key: str, base_url: str = BASE_URL, timeout: float = 10.0):
+        self.api_key = api_key
+        self.base_url = base_url
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "X-API-Key": self.api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "dcoink-python-sdk/0.1.0"
+            },
+            timeout=timeout
+        )
+
+    def _handle_error(self, response: httpx.Response):
+        try:
+            data = response.json()
+            error_code = data.get("error", "unknown_error")
+            message = data.get("message", response.text)
+        except Exception:
+            error_code = "unknown_error"
+            message = response.text
+
+        status = response.status_code
+        if status == 401:
+            raise AuthenticationError(message, error_code, status)
+        elif status == 403:
+            raise ForbiddenError(message, error_code, status)
+        elif status == 409:
+            raise CodeTakenError(message, error_code, status)
+        elif status == 429:
+            raise RateLimitError("Rate limit exceeded", error_code, status)
+        elif status == 400:
+            raise ValidationError(message, error_code, status)
+        else:
+            raise DcoApiError(message, error_code, status)
+
+    def _request(self, method: str, path: str, **kwargs) -> Any:
+        response = self._client.request(method, path, **kwargs)
+        if not response.is_success:
+            self._handle_error(response)
+        
+        # 204 No Content handling
+        if response.status_code == 204 or not response.content:
+            return None
+            
+        return response.json()
+
+    def get_me(self) -> UserInfo:
+        """Get the current authenticated user's details."""
+        data = self._request("GET", "/api/auth/me")
+        return UserInfo.from_dict(data)
+
+    def create_link(self, url: str, custom_code: Optional[str] = None) -> Link:
+        """Create a new shortened link."""
+        payload = {"url": url}
+        if custom_code:
+            payload["custom_code"] = custom_code
+            
+        data = self._request("POST", "/api/links", json=payload)
+        return Link(
+            short_code=data["short_code"],
+            short_url=data["short_url"],
+            target_url=data.get("target_url", url),
+            expires_at=data.get("expires_at")
+        )
+
+    def list_links(self, limit: int = 50, offset: int = 0) -> List[Link]:
+        """List all links created by the current user."""
+        data = self._request("GET", "/api/links", params={"limit": limit, "offset": offset})
+        links = []
+        for item in data.get("links", []):
+            links.append(Link(
+                short_code=item["short_code"],
+                short_url=f"https://dco.ink/{item['short_code']}",
+                target_url=item.get("target_url"),
+                created_at=item.get("created_at"),
+                expires_at=item.get("expires_at")
+            ))
+        return links
+
+    def update_link(self, short_code: str, new_url: str) -> None:
+        """Update the target URL of an existing link."""
+        self._request("PUT", f"/api/links/{short_code}", json={"url": new_url})
+
+    def delete_link(self, short_code: str) -> None:
+        """Delete an existing link."""
+        self._request("DELETE", f"/api/links/{short_code}")
+
+    def close(self):
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

dcoink-0.1.0/dcoink/errors.py

@@ -0,0 +1,29 @@
+from typing import Optional
+
+class DcoApiError(Exception):
+    """Base class for all API errors."""
+    def __init__(self, message: str, code: Optional[str] = None, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+
+class AuthenticationError(DcoApiError):
+    """Raised when the API key is missing or invalid."""
+    pass
+
+class ValidationError(DcoApiError):
+    """Raised when the provided URL or custom code is invalid."""
+    pass
+
+class CodeTakenError(DcoApiError):
+    """Raised when the requested custom code is already in use."""
+    pass
+
+class ForbiddenError(DcoApiError):
+    """Raised when the user attempts an action they do not have permission for."""
+    pass
+
+class RateLimitError(DcoApiError):
+    """Raised when the API rate limit is exceeded."""
+    pass

dcoink-0.1.0/dcoink/models.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass
+from typing import Optional, List
+
+@dataclass
+class Link:
+    """Represents a shortened link."""
+    short_code: str
+    short_url: str
+    target_url: Optional[str] = None
+    id: Optional[str] = None
+    clicks: int = 0
+    created_at: Optional[str] = None
+    expires_at: Optional[str] = None
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> 'Link':
+        valid_keys = {k for k in cls.__annotations__}
+        filtered = {k: v for k, v in data.items() if k in valid_keys}
+        return cls(**filtered)
+
+@dataclass
+class UserInfo:
+    """Represents the authenticated user's details."""
+    id: str
+    email: str
+    name: str
+    is_subscribed: int
+    api_token: str
+    avatar_url: Optional[str] = None
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> 'UserInfo':
+        valid_keys = {k for k in cls.__annotations__}
+        filtered = {k: v for k, v in data.items() if k in valid_keys}
+        return cls(**filtered)

dcoink-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dcoink"
+version = "0.1.0"
+description = "The official Python SDK for dco.ink - A minimalist and developer-friendly URL shortener"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+  { name = "dco.ink", email = "hello@dco.ink" },
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "httpx>=0.24.0"
+]
+
+[project.urls]
+"Homepage" = "https://dco.ink"
+"Source" = "https://github.com/dco/dco-ink-tools"
+
+[project.scripts]
+dcoink = "dcoink.cli:main"

dcoink-0.1.0/test_sdk.py

@@ -0,0 +1,36 @@
+import asyncio
+import os
+import dcoink
+
+# User provided testing token
+TEST_TOKEN = os.getenv("DCO_API_KEY", "your_api_key_here")
+
+def test_sync():
+    print("--- 1. Testing Sync Anonymous ---")
+    link = dcoink.shorten("https://google.com")
+    print(f"✅ Anonymous link generated: {link.short_url} (Code: {link.short_code})")
+
+    print("\n--- 2. Testing Sync Client (Authenticated) ---")
+    with dcoink.Client(api_key=TEST_TOKEN) as client:
+        # Get Me
+        me = client.get_me()
+        print(f"✅ User Info: {me.name} ({me.email}) - Subscribed: {me.is_subscribed}")
+        
+        # Create link
+        link2 = client.create_link("https://github.com/dcoink")
+        print(f"✅ Authenticated link generated: {link2.short_url}")
+        
+        # List links
+        links = client.list_links(limit=5)
+        print(f"✅ Found {len(links)} links in history.")
+
+async def test_async():
+    print("\n--- 3. Testing Async Client (Authenticated) ---")
+    async with dcoink.AsyncClient(api_key=TEST_TOKEN) as client:
+        me = await client.get_me()
+        print(f"✅ Async User Info: {me.name} ({me.email})")
+
+if __name__ == "__main__":
+    test_sync()
+    asyncio.run(test_async())
+    print("\n🎉 All SDK tests passed!")