Metadata-Version: 2.4
Name: apiforge-sdk
Version: 0.1.0
Summary: Unified Python interface for multiple APIs with plugin architecture
Project-URL: Homepage, https://github.com/apiforge/apiforge
Project-URL: Documentation, https://github.com/apiforge/apiforge/blob/main/README.md
Project-URL: Repository, https://github.com/apiforge/apiforge
Project-URL: Issues, https://github.com/apiforge/apiforge/issues
Project-URL: Changelog, https://github.com/apiforge/apiforge/releases
Author-email: APIForge Contributors <maintainers@apiforge.dev>
Maintainer-email: APIForge Contributors <maintainers@apiforge.dev>
License: MIT License
        
        Copyright (c) 2026 APIForge Contributors
        
        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.
License-File: LICENSE
Keywords: api,discord,github,integration,mcp,notion,openapi,plugins,sdk
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.27.0
Requires-Dist: keyring>=24.3.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: rich>=13.7.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Description-Content-Type: text/markdown

# APIForge

> One Python interface for thousands of APIs.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![CI](https://github.com/apiforge/apiforge/actions/workflows/ci.yml/badge.svg)](https://github.com/apiforge/apiforge/actions/workflows/ci.yml)

APIForge is a plugin-based Python framework that gives you a single,
consistent way to talk to many APIs. The first release ships with
plugins for **GitHub**, **Discord**, and **Notion**; the architecture
is designed to grow to thousands.

```python
from apiforge import APIForge

client = APIForge()
client.configure(
    github_token="ghp_...",
    discord_token="...",
    notion_token="...",
)

# All of these look the same — no separate SDK to learn per service.
user    = client.github.get_user("octocat")
msg     = client.discord.send_message(channel_id="...", content="hi")
pages   = client.notion.list_pages()
```

The same client also exposes a CLI:

```bash
apiforge list
apiforge plugins
apiforge info github
```

---

## Why APIForge?

If you integrate with five services, you install five SDKs, learn
five authentication schemes, and maintain five upgrade cycles.
APIForge collapses that into one.

- **One import.** `from apiforge import APIForge`.
- **One auth surface.** Pass tokens once; they reach every plugin.
- **One plugin contract.** Adding a new service is a small, well-defined job.
- **One way to fail.** A small exception hierarchy that you can catch in one place.
- **One direction.** Async-first under the hood, with sync wrappers for ergonomics.

---

## Installation

```bash
pip install apiforge
```

The base package installs the three first-party plugins
(GitHub, Discord, Notion) automatically. Additional plugins are
distributed as separate packages, e.g.:

```bash
pip install apiforge-plugin-stripe
```

Each one registers itself via the standard `apiforge.plugins`
entry-point group — there's nothing to wire up in your code.

---

## Quickstart

### Sync usage

The simplest path. Every method on a plugin is awaitable under the
hood, but the client exposes a transparent sync wrapper, so you don't
need an event loop for one-off scripts:

```python
from apiforge import APIForge

client = APIForge()
client.configure(github_token="ghp_...")

user = client.github.get_user("octocat")
print(user["login"])
```

### Async usage

For servers, batched jobs, or anything that benefits from concurrency:

```python
import asyncio
from apiforge import APIForge

async def main() -> None:
    async with APIForge() as client:
        client.configure(github_token="ghp_...")
        user, repos = await asyncio.gather(
            client.github.get_user("octocat"),
            client.github.list_repos("octocat", limit=5),
        )

asyncio.run(main())
```

### Credentials

APIForge looks for credentials in this order:

1. **Explicit** — `client.configure(github_token="...")`
2. **Environment** — `APIFORGE_GITHUB_TOKEN=...`
3. **Keyring** — the OS secure store (`keyring` package)
4. **Config file** — `~/.config/apiforge/credentials.toml`

```bash
# Store a token in your OS keyring:
python -c "from apiforge import APIForge; APIForge().credentials.store('github', 'ghp_...')"
```

---

## CLI

```bash
apiforge list               # all registered plugins
apiforge plugins            # alias for `list`
apiforge info github        # details on one plugin
apiforge info notion --json # machine-readable

# Coming in later phases:
apiforge generate openapi.yaml --name myplugin  # Phase 2
apiforge install apiforge-plugin-stripe          # Phase 5
apiforge update                                  # Phase 5
```

---

## Writing a Plugin

A plugin is a class that subclasses `BasePlugin` and declares a
`PluginMetadata`:

```python
from apiforge.plugins.base import BasePlugin
from apiforge.core.metadata import AuthType, OperationMetadata, PluginMetadata


class StripePlugin(BasePlugin):
    metadata = PluginMetadata(
        name="stripe",
        version="0.1.0",
        description="Stripe payments API.",
        auth_type=AuthType.API_KEY,
        base_url="https://api.stripe.com/v1",
        operations=(
            OperationMetadata(name="create_charge", parameters={"amount": "int"}),
        ),
    )

    async def setup(self) -> None:
        ...

    async def create_charge(self, amount: int) -> dict:
        ...
```

Then register it in your package's `pyproject.toml`:

```toml
[project.entry-points."apiforge.plugins"]
stripe = "apiforge_plugin_stripe:StripePlugin"
```

Once installed, `client.stripe.create_charge(...)` works out of the
box. See [Contributing.md](Contributing.md) for the full checklist.

---

## Project Status

APIForge is in **alpha**. The core framework, the credential
manager, the CLI, and the three first-party plugins are stable
enough for everyday use, but the API may still evolve.

See [ROADMAP.md](ROADMAP.md) for what's next.

---

## Documentation

- [Architecture.md](Architecture.md) — the design, the layers, the contracts.
- [Contributing.md](Contributing.md) — how to write and ship a plugin.
- [ROADMAP.md](ROADMAP.md) — Phase 1 through Phase 5.

---

## License

MIT — see [LICENSE](LICENSE).