apiforge-sdk 0.1.0__tar.gz

apiforge_sdk-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage artifacts
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local config
+.env
+.env.local
+config.local.toml
+*.local.toml

apiforge_sdk-0.1.0/Contributing.md

@@ -0,0 +1,260 @@
+# Contributing to APIForge
+
+Thanks for your interest in improving APIForge! This document walks
+you through the plugin development workflow, the codebase layout,
+the conventions we use, and how to send a pull request.
+
+---
+
+## Code of conduct
+
+Be respectful, assume good faith, and remember there is a person on
+the other side of the screen. We follow the
+[Contributor Covenant](https://www.contributor-covenant.org/).
+
+---
+
+## Setting up your environment
+
+```bash
+git clone https://github.com/apiforge/apiforge.git
+cd apiforge
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,test]"
+```
+
+Run the tests:
+
+```bash
+pytest
+```
+
+Lint:
+
+```bash
+ruff check apiforge tests
+ruff format --check apiforge tests
+```
+
+Type-check:
+
+```bash
+mypy apiforge
+```
+
+All three checks run in CI; see `.github/workflows/ci.yml`.
+
+---
+
+## Code layout
+
+```
+apiforge/
+├── core/                ← client, config, credentials, discovery, metadata
+├── plugins/             ← first-party plugins (GitHub, Discord, Notion)
+├── mcp/                 ← MCP adapter base + generator (Phase 4)
+├── generators/          ← OpenAPI generator (Phase 2)
+└── cli/                 ← the `apiforge` command
+
+tests/
+├── test_core/
+└── test_plugins/
+```
+
+The rule of thumb:
+
+- Cross-cutting concerns go in `core/`.
+- Each service has its own plugin directory under `plugins/`.
+- Adapters and generators are interface-first today; they grow
+  alongside the plugins they serve.
+
+---
+
+## Adding a new plugin
+
+The fastest path: copy an existing plugin (`apiforge/plugins/github/`)
+and adapt it. The full checklist:
+
+### 1. Create the package
+
+```
+apiforge/plugins/<name>/__init__.py
+```
+
+For a standalone distribution, the directory name should be
+`<name>.py` or a package. The class name must be unique.
+
+### 2. Define metadata
+
+```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",
+                description="Charge a customer.",
+                parameters={"amount": "int", "currency": "str"},
+            ),
+        ),
+    )
+```
+
+`PluginMetadata` is strict — extra fields are rejected. The fields
+you should fill in:
+
+- `name` — unique, lowercase, matches the entry-point name.
+- `version` — semver.
+- `description` — one sentence, used in `apiforge list`.
+- `auth_type` — one of `token`, `api_key`, `oauth2`, `basic`, `none`.
+- `base_url` — the upstream root; some plugins don't have one.
+- `operations` — at minimum the operations you implement.
+- `openapi_url` — if the upstream publishes a spec.
+
+### 3. Implement operations
+
+```python
+async def create_charge(self, amount: int, currency: str) -> dict:
+    token = self.require_credential()
+    response = await self.http.post(
+        f"{self.metadata.base_url}/charges",
+        json={"amount": amount, "currency": currency},
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    response.raise_for_status()
+    return response.json()
+```
+
+Conventions:
+
+- All operations are `async def`.
+- Use `self.http`, not your own client — we share the pool.
+- Use `self.require_credential()` if a credential is mandatory.
+- Use `self.get_credential()` if it's optional (e.g. for read-only
+  endpoints).
+- Don't catch `HTTPStatusError` — let it propagate so the CLI can
+  show the upstream status.
+
+### 4. Wire the entry point
+
+In your `pyproject.toml`:
+
+```toml
+[project.entry-points."apiforge.plugins"]
+stripe = "apiforge_plugin_stripe:StripePlugin"
+```
+
+If you're adding to APIForge itself, edit the top-level
+`pyproject.toml` instead.
+
+### 5. Add tests
+
+Cover at minimum:
+
+- The plugin's happy path, with `httpx` mocked via `respx`.
+- The credential-missing path, if your plugin requires one.
+- Auth headers — assert the right `Authorization` header is sent.
+
+See `tests/test_plugins/test_first_party.py` for examples.
+
+### 6. Document
+
+Add a one-paragraph section to the README under "Plugins".
+Reference the upstream API docs.
+
+---
+
+## Adding an MCP adapter (Phase 4 preview)
+
+When the MCP generation machinery lands, your plugin will need to
+declare an adapter:
+
+```python
+from apiforge.mcp.adapter import BaseMCPAdapter
+
+
+class StripeMCPAdapter(BaseMCPAdapter):
+    def tool_definitions(self) -> list[dict]:
+        return [
+            {
+                "name": "stripe__create_charge",
+                "description": "Charge a customer.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "amount": {"type": "integer"},
+                        "currency": {"type": "string"},
+                    },
+                    "required": ["amount", "currency"],
+                },
+            }
+        ]
+
+
+class StripePlugin(BasePlugin):
+    metadata = PluginMetadata(name="stripe", version="0.1.0", ...)
+    MCP_ADAPTER_CLASS = StripeMCPAdapter
+```
+
+The contract is stable today; the generator walks the registry
+looking for `MCP_ADAPTER_CLASS`.
+
+---
+
+## Style
+
+- **Python 3.12+** syntax — `type` aliases, `match`, generics.
+- **Type hints everywhere** public. Internal helpers can use less
+  formal types where it helps readability.
+- **Pydantic models** for any data that crosses a boundary (config,
+  metadata, request/response shapes).
+- **Ruff** for linting and formatting. Run `ruff format` before
+  committing.
+- **mypy --strict** is the type-check setting.
+
+---
+
+## Pull request checklist
+
+- [ ] Tests pass locally (`pytest`)
+- [ ] Ruff is clean (`ruff check apiforge tests`)
+- [ ] mypy is clean (`mypy apiforge`)
+- [ ] New code is type-hinted
+- [ ] New public surface is documented (docstrings + README update
+      if user-facing)
+- [ ] If you added a plugin, the entry point is wired in
+      `pyproject.toml`
+- [ ] CHANGELOG entry (we'll add one once we're out of 0.0.x)
+
+---
+
+## Release process
+
+We use `hatch` for builds. To cut a release:
+
+```bash
+# Bump version, update CHANGELOG.
+# Tag and push:
+git tag -a v0.2.0 -m "v0.2.0"
+git push origin v0.2.0
+```
+
+CI builds the wheel and sdist; we publish from CI with PyPI trusted
+publishing.
+
+---
+
+## Questions?
+
+Open a GitHub Discussion. Bug reports go in Issues. Security
+disclosures: see `SECURITY.md` (TODO — please open an issue for now
+and we'll route it).

apiforge_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

apiforge_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,264 @@
+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).