Metadata-Version: 2.4
Name: instanode
Version: 0.3.0
Summary: Official Python SDK for instanode.dev — zero-setup Postgres + webhooks for AI agents
License: MIT
Project-URL: Homepage, https://instanode.dev
Project-URL: Documentation, https://instanode.dev/llms.txt
Project-URL: Repository, https://github.com/InstaNode-dev/sdk-python
Project-URL: Bug Tracker, https://github.com/InstaNode-dev/sdk-python/issues
Keywords: postgres,webhook,database,developer-tools,ai-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# instanode

Official Python SDK for [instanode.dev](https://instanode.dev) — zero-setup
Postgres databases and webhook receivers for AI agents and humans. No Docker,
no account for the free tier.

```
pip install instanode
```

## Quickstart

```python
import instanode

client = instanode.Client()

# Postgres (pgvector pre-installed). Free tier: 10 MB / 2 connections / 24h TTL.
db = client.provision_database(name="my-app")
print(db.connection_url)   # postgres://…@pg.instanode.dev:5432/db_…

# Webhook receiver. Free tier: 100 requests stored / 24h TTL.
hook = client.provision_webhook(name="stripe-events")
print(hook.connection_url) # https://api.instanode.dev/webhook/receive/<token>
```

Use `db.connection_url` with psycopg, asyncpg, SQLAlchemy, Prisma, Drizzle,
or anything else that speaks Postgres.

### Async

```python
import asyncio
import instanode.aio

async def main():
    async with instanode.aio.AsyncClient() as client:
        db = await client.provision_database(name="my-app")
        print(db.connection_url)

asyncio.run(main())
```

### Paid tier

The free tier caps each /24 subnet at 5 provisions/day and resources expire
in 24 hours. To lift the caps and make resources permanent, sign up at
[instanode.dev](https://instanode.dev), mint a bearer token from the
dashboard, and set it:

```python
client = instanode.Client(api_key="eyJ…")
# Or via env: export INSTANODE_API_KEY=eyJ…
```

### Account operations (paid tier)

```python
# Claim an anonymous resource into the account (clears the 24h expiry).
client.claim(token=db.token)

# List everything this account owns.
for r in client.list_resources():
    print(r.resource_type, r.token, r.tier, r.created_at)

# Delete a resource.
client.delete_resource(db.token)

# Mint a fresh 30-day JWT from a session-authenticated context.
jwt = client.get_api_token()
```

## Error handling

```python
from instanode import InstanodeError

try:
    client.provision_database(name="my-app")
except InstanodeError as e:
    if e.is_rate_limited():
        # …retry later
        ...
    elif e.is_unauthorized():
        # …bad or missing API key
        ...
    else:
        raise
```

`InstanodeError` exposes `status_code`, `code`, and `message`, plus convenience
checks: `is_not_found()`, `is_unauthorized()`, `is_forbidden()`,
`is_rate_limited()`, `is_conflict()`, `is_service_unavailable()`.

## Scope

This `0.3.0` release covers what the live API actually exposes today:

- `POST /db/new` → `provision_database`
- `POST /webhook/new` → `provision_webhook`
- `POST /api/me/claim` → `claim`
- `GET  /api/me/resources` → `list_resources`
- `DELETE /api/me/resources/{token}` → `delete_resource`
- `GET  /api/me/token` → `get_api_token`

Monitor/heartbeat, cache (Redis), MongoDB, NATS queue, and credential
rotation are on the roadmap. They live on the [`feature/full-api`
branch](https://github.com/InstaNode-dev/sdk-python/tree/feature/full-api)
and will land in a later minor release once the backend ships them. Pin
to that branch explicitly if you want the preview surface today:

```
pip install git+https://github.com/InstaNode-dev/sdk-python.git@feature/full-api
```

## Related

- MCP server (Claude Code / Cursor / Windsurf): <https://www.npmjs.com/package/@instanode/mcp>
- LangChain tools: <https://pypi.org/project/langchain-instanode/>
- LlamaIndex tools: <https://pypi.org/project/llama-index-tools-instanode/>
- CrewAI tools: <https://pypi.org/project/crewai-instanode-tools/>
- HTTP API reference: <https://instanode.dev/llms.txt>

## License

MIT. See [`LICENSE`](./LICENSE).
