manikineko 0.2.0__tar.gz

manikineko-0.2.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: manikineko
+Version: 0.2.0
+Summary: Official SDK for Manikineko — Discord-compatible REST, realtime gateway, OAuth2 and app-controlled gateway servers.
+Author: Manikineko
+License-Expression: MIT
+Project-URL: Homepage, https://manikineko.nl
+Keywords: manikineko,chat,bot,discord-compatible,oauth2
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: gateway
+Requires-Dist: websockets>=12; extra == "gateway"
+Provides-Extra: all
+Requires-Dist: websockets>=12; extra == "all"
+
+# manikineko (Python SDK)
+
+Official SDK for the [Manikineko](https://manikineko.nl) platform.
+Python >= 3.9. REST + OAuth2 helpers are stdlib-only; the realtime gateway
+needs the `websockets` package.
+
+```bash
+pip install manikineko            # REST + OAuth only
+pip install "manikineko[gateway]" # + realtime gateway (websockets)
+```
+
+## Bot quickstart
+
+```python
+from manikineko import Client
+
+client = Client(
+    base_url="https://api.manikineko.nl",  # your instance's API host
+    token="BOT_TOKEN",                     # from the developer portal
+    token_type="bot",
+)
+
+@client.event
+async def on_ready(ready):
+    print(f"Logged in as {ready['user']['username']}")
+
+@client.event
+async def on_message_create(msg):
+    if msg.get("author", {}).get("bot"):
+        return
+    if msg.get("content") == "!ping":
+        client.say(msg["channel_id"], "pong")
+
+client.run()  # connects the gateway, blocks forever
+```
+
+The SDK speaks the Discord-compatible API (`/api/v10`): snowflake IDs,
+integer channel types, Discord-shaped events — so discord.py-style code
+ports over easily. REST methods are synchronous; event handlers may be
+sync or async.
+
+## What's covered
+
+- **REST** — users, guilds, channels, messages, reactions, pins, typing,
+  members, bans, roles, invites, audit logs, DMs, reports, HTML channels.
+- **Gateway** — `client.run()`, heartbeats, reconnects, `@client.event`,
+  `gateway.request_members()`, `client.set_presence()`.
+- **Voice / VC** — join/leave calls in *any* channel type (incl. DMs),
+  voice states, mute/deafen/move moderation, LiveKit credentials or mesh
+  WebRTC signalling, `VOICE_STATE_UPDATE` events.
+- **PSTN dialer** — `client.dialer()` places real phone calls into voice
+  channels when the instance has SIP/VoIP configured.
+- **Custom emotes** — platform + guild emote listing/CRUD, usable-set
+  endpoint, `Client.emoji_tag()` helper for `<:name:id>` content.
+- **Entitlements** — marketplace app integrations: who owns your app.
+- **Urgent popups** — fetch/acknowledge forced system-bot notices.
+- **Uploads** — `send_message(channel, files=[...])` or `upload_file()`.
+- **OAuth2** — `OAuth2Client`: authorize URLs, PKCE, code exchange, refresh,
+  client_credentials, revocation, `@me`.
+- **App push API** — `app_servers()`, `app_create_channel()`,
+  `app_send_message()`, `app_dispatch_event()` for app-controlled gateway
+  servers; guild link config via `set_guild_gateway()`.
+- **Lexicons** — `list_lexicons()`, `put_lexicon()`, `delete_lexicon()`.
+- **Webhooks** — `verify_gateway_signature()` verifies
+  `X-Manikineko-Signature` headers on app-gateway deliveries.
+- **Admin** — `client.admin` namespace (staff JWT): system bots, VoIP
+  trunks/numbers/credits, maintenance purges, urgent popups.
+
+## Voice / calls
+
+Every channel type can host a call — including DM and group DM channels
+(recipient-only). Voice state changes arrive as `VOICE_STATE_UPDATE`.
+
+```python
+cfg = client.get_voice_config()     # {"provider": ..., "voip": bool}
+
+# Join a call (any channel). When LiveKit is the media backend the
+# response carries a "livekit" dict {"url", "token"} for a LiveKit SDK.
+state = client.join_voice_channel(channel_id, self_mute=True)
+
+client.update_voice_state(self_mute=False)
+participants = client.get_voice_states(channel_id)
+client.leave_voice_channel()
+
+# Moderation (server channels only):
+client.voice_mute_member(channel_id, user_id, True)
+client.voice_disconnect_member(channel_id, user_id)
+client.voice_move_member(other_channel_id, user_id)
+```
+
+### PSTN dialer (SIP)
+
+When the instance has telephony configured (`VOIP_ENABLED` + SIP trunks),
+bots and users can dial real phone numbers into a voice channel. Outbound
+calls are metered in call credits (HTTP 402 = top up via the shop).
+
+```python
+dialer = client.dialer()
+if dialer.available():
+    print("credits:", dialer.credits())
+
+    # auto-joins the voice channel, then dials:
+    call = dialer.dial(channel_id, "+15551234567")
+    print(call.id, call.status)                # ringing
+
+    call.wait_for_connect()                    # status == "active"
+    # ... the phone party is now in the voice room ...
+    call.hangup()                              # or call.wait_for_end()
+```
+
+Lower-level primitives are on the client too: `dial_phone()`,
+`get_call()`, `get_channel_calls()`, `hangup_call()`, `get_call_credits()`,
+`get_call_credit_history()`. Inbound calls to an instance DID ring into
+the linked voice channel.
+
+## Custom emotes
+
+```python
+emojis = client.get_guild_emojis(guild_id)
+client.create_guild_emoji(guild_id, "nyaa", "https://cdn…/nyaa.png")
+
+# in message content: ":nyaa:" resolves by name, or use a tag by ID:
+client.say(channel_id, f"hello {Client.emoji_tag(emojis[0])}")
+
+usable = client.get_usable_emojis()   # picker payload
+```
+
+Server emotes outside their home guild need premium; violations return 403.
+
+## Entitlements (marketplace app integrations)
+
+```python
+# As a user:
+owned = client.get_my_entitlements()
+
+# As an app (bot token or client_credentials + applications.gateway):
+all_owners = app_client.app_entitlements()
+check = app_client.app_check_entitlement(user_id)   # {"entitled": True}
+```
+
+## Urgent popups
+
+System bots can push forced popups (`type="urgent"`, or admin urgent
+messages). Users see them on `URGENT_MESSAGE` gateway events and via
+`GET /urgent/pending`:
+
+```python
+@client.on("URGENT_MESSAGE")
+def on_urgent(u):
+    print("URGENT:", u["title"], u["body"])
+
+pending = client.get_pending_urgent_messages()
+client.acknowledge_urgent(pending[0]["id"])    # dismiss
+```
+
+## Admin API
+
+`client.admin` targets `/api/v1/admin/*` and needs a staff JWT
+(`token_type="bearer"`). IDs on this surface are native UUIDs.
+
+```python
+admin = client.admin
+
+admin.system_bots.send_message(
+    bot_id, user_ids=[uid1, uid2],
+    content="scheduled maintenance tonight",
+    type="urgent", severity="warning", title="Heads up",
+)
+
+admin.voip.create_trunk(name="twilio", carrier="twilio-byoc",
+                        host="…sip.twilio.com", prefixes=["+1"],
+                        rate_credits=2)
+admin.voip.adjust_credits(user_id=uid, amount=100, note="promo")
+
+admin.maintenance.purge_stale_reports()
+admin.urgent.create(title="v2 launched", body="…", scope="global")
+```
+
+## Auth
+
+| Token kind | `token_type` | Notes |
+| --- | --- | --- |
+| Bot token | `"bot"` (default) | `Authorization: Bot <token>` |
+| OAuth2 access token | `"bearer"` | Scoped — see `Scope` constants |
+| User JWT | `"bearer"` | First-party session token |
+
+## OAuth2 ("Login with Manikineko")
+
+```python
+from manikineko import OAuth2Client, generate_pkce
+
+oauth = OAuth2Client(
+    base_url="https://api.manikineko.nl",
+    client_id="YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+    redirect_uri="https://myapp.example/callback",
+)
+
+verifier, challenge = generate_pkce()
+url = oauth.authorize_url(["identify", "email"], state=state, code_challenge=challenge)
+
+# In your callback handler:
+tokens = oauth.exchange_code(code, code_verifier=verifier)
+me = oauth.user(tokens["access_token"])          # GET /users/@me
+later = oauth.refresh_token(tokens["refresh_token"])
+oauth.revoke(tokens["access_token"])
+```
+
+`client_credentials` tokens (e.g. `scope="applications.gateway"`) call the
+app push API:
+
+```python
+tok = oauth.client_credentials("applications.gateway")
+app = Client(base_url, token=tok["access_token"], token_type="bearer")
+for server in app.app_servers():
+    app.app_send_message(server["id"], channel_id, "hello from my app")
+    app.app_dispatch_event(server["id"], "score_update", data={"score": 42})
+```
+
+## Gateway events
+
+Dispatch names mirror Discord: `READY`, `MESSAGE_CREATE`, `MESSAGE_UPDATE`,
+`MESSAGE_DELETE`, `CHANNEL_*`, `GUILD_*`, `GUILD_MEMBER_*`, `GUILD_ROLE_*`,
+`GUILD_BAN_*`, `MESSAGE_REACTION_*`, `PRESENCE_UPDATE`, `TYPING_START`,
+`INVITE_*`, `VOICE_STATE_UPDATE`. Manikineko extras: `APP_EVENT`,
+`URGENT_MESSAGE`, `WARNING_RECEIVED`, `USER_SUSPENDED`, `USER_BANNED`.
+
+```python
+@client.on("*")
+def log_all(payload):
+    print(payload["event"], payload["data"])
+```
+
+## Escape hatches
+
+```python
+client.request("GET", "/channels/123/messages")   # compat API
+client.api("GET", "/themes")                      # native /api/v1
+```
+
+## Errors
+
+`APIError` (`.status`, `.code`, `.body`), `OAuthError` (`.error`,
+`.error_description`), `InvalidSessionError` on bad gateway tokens.

manikineko-0.2.0/README.md

@@ -0,0 +1,244 @@
+# manikineko (Python SDK)
+
+Official SDK for the [Manikineko](https://manikineko.nl) platform.
+Python >= 3.9. REST + OAuth2 helpers are stdlib-only; the realtime gateway
+needs the `websockets` package.
+
+```bash
+pip install manikineko            # REST + OAuth only
+pip install "manikineko[gateway]" # + realtime gateway (websockets)
+```
+
+## Bot quickstart
+
+```python
+from manikineko import Client
+
+client = Client(
+    base_url="https://api.manikineko.nl",  # your instance's API host
+    token="BOT_TOKEN",                     # from the developer portal
+    token_type="bot",
+)
+
+@client.event
+async def on_ready(ready):
+    print(f"Logged in as {ready['user']['username']}")
+
+@client.event
+async def on_message_create(msg):
+    if msg.get("author", {}).get("bot"):
+        return
+    if msg.get("content") == "!ping":
+        client.say(msg["channel_id"], "pong")
+
+client.run()  # connects the gateway, blocks forever
+```
+
+The SDK speaks the Discord-compatible API (`/api/v10`): snowflake IDs,
+integer channel types, Discord-shaped events — so discord.py-style code
+ports over easily. REST methods are synchronous; event handlers may be
+sync or async.
+
+## What's covered
+
+- **REST** — users, guilds, channels, messages, reactions, pins, typing,
+  members, bans, roles, invites, audit logs, DMs, reports, HTML channels.
+- **Gateway** — `client.run()`, heartbeats, reconnects, `@client.event`,
+  `gateway.request_members()`, `client.set_presence()`.
+- **Voice / VC** — join/leave calls in *any* channel type (incl. DMs),
+  voice states, mute/deafen/move moderation, LiveKit credentials or mesh
+  WebRTC signalling, `VOICE_STATE_UPDATE` events.
+- **PSTN dialer** — `client.dialer()` places real phone calls into voice
+  channels when the instance has SIP/VoIP configured.
+- **Custom emotes** — platform + guild emote listing/CRUD, usable-set
+  endpoint, `Client.emoji_tag()` helper for `<:name:id>` content.
+- **Entitlements** — marketplace app integrations: who owns your app.
+- **Urgent popups** — fetch/acknowledge forced system-bot notices.
+- **Uploads** — `send_message(channel, files=[...])` or `upload_file()`.
+- **OAuth2** — `OAuth2Client`: authorize URLs, PKCE, code exchange, refresh,
+  client_credentials, revocation, `@me`.
+- **App push API** — `app_servers()`, `app_create_channel()`,
+  `app_send_message()`, `app_dispatch_event()` for app-controlled gateway
+  servers; guild link config via `set_guild_gateway()`.
+- **Lexicons** — `list_lexicons()`, `put_lexicon()`, `delete_lexicon()`.
+- **Webhooks** — `verify_gateway_signature()` verifies
+  `X-Manikineko-Signature` headers on app-gateway deliveries.
+- **Admin** — `client.admin` namespace (staff JWT): system bots, VoIP
+  trunks/numbers/credits, maintenance purges, urgent popups.
+
+## Voice / calls
+
+Every channel type can host a call — including DM and group DM channels
+(recipient-only). Voice state changes arrive as `VOICE_STATE_UPDATE`.
+
+```python
+cfg = client.get_voice_config()     # {"provider": ..., "voip": bool}
+
+# Join a call (any channel). When LiveKit is the media backend the
+# response carries a "livekit" dict {"url", "token"} for a LiveKit SDK.
+state = client.join_voice_channel(channel_id, self_mute=True)
+
+client.update_voice_state(self_mute=False)
+participants = client.get_voice_states(channel_id)
+client.leave_voice_channel()
+
+# Moderation (server channels only):
+client.voice_mute_member(channel_id, user_id, True)
+client.voice_disconnect_member(channel_id, user_id)
+client.voice_move_member(other_channel_id, user_id)
+```
+
+### PSTN dialer (SIP)
+
+When the instance has telephony configured (`VOIP_ENABLED` + SIP trunks),
+bots and users can dial real phone numbers into a voice channel. Outbound
+calls are metered in call credits (HTTP 402 = top up via the shop).
+
+```python
+dialer = client.dialer()
+if dialer.available():
+    print("credits:", dialer.credits())
+
+    # auto-joins the voice channel, then dials:
+    call = dialer.dial(channel_id, "+15551234567")
+    print(call.id, call.status)                # ringing
+
+    call.wait_for_connect()                    # status == "active"
+    # ... the phone party is now in the voice room ...
+    call.hangup()                              # or call.wait_for_end()
+```
+
+Lower-level primitives are on the client too: `dial_phone()`,
+`get_call()`, `get_channel_calls()`, `hangup_call()`, `get_call_credits()`,
+`get_call_credit_history()`. Inbound calls to an instance DID ring into
+the linked voice channel.
+
+## Custom emotes
+
+```python
+emojis = client.get_guild_emojis(guild_id)
+client.create_guild_emoji(guild_id, "nyaa", "https://cdn…/nyaa.png")
+
+# in message content: ":nyaa:" resolves by name, or use a tag by ID:
+client.say(channel_id, f"hello {Client.emoji_tag(emojis[0])}")
+
+usable = client.get_usable_emojis()   # picker payload
+```
+
+Server emotes outside their home guild need premium; violations return 403.
+
+## Entitlements (marketplace app integrations)
+
+```python
+# As a user:
+owned = client.get_my_entitlements()
+
+# As an app (bot token or client_credentials + applications.gateway):
+all_owners = app_client.app_entitlements()
+check = app_client.app_check_entitlement(user_id)   # {"entitled": True}
+```
+
+## Urgent popups
+
+System bots can push forced popups (`type="urgent"`, or admin urgent
+messages). Users see them on `URGENT_MESSAGE` gateway events and via
+`GET /urgent/pending`:
+
+```python
+@client.on("URGENT_MESSAGE")
+def on_urgent(u):
+    print("URGENT:", u["title"], u["body"])
+
+pending = client.get_pending_urgent_messages()
+client.acknowledge_urgent(pending[0]["id"])    # dismiss
+```
+
+## Admin API
+
+`client.admin` targets `/api/v1/admin/*` and needs a staff JWT
+(`token_type="bearer"`). IDs on this surface are native UUIDs.
+
+```python
+admin = client.admin
+
+admin.system_bots.send_message(
+    bot_id, user_ids=[uid1, uid2],
+    content="scheduled maintenance tonight",
+    type="urgent", severity="warning", title="Heads up",
+)
+
+admin.voip.create_trunk(name="twilio", carrier="twilio-byoc",
+                        host="…sip.twilio.com", prefixes=["+1"],
+                        rate_credits=2)
+admin.voip.adjust_credits(user_id=uid, amount=100, note="promo")
+
+admin.maintenance.purge_stale_reports()
+admin.urgent.create(title="v2 launched", body="…", scope="global")
+```
+
+## Auth
+
+| Token kind | `token_type` | Notes |
+| --- | --- | --- |
+| Bot token | `"bot"` (default) | `Authorization: Bot <token>` |
+| OAuth2 access token | `"bearer"` | Scoped — see `Scope` constants |
+| User JWT | `"bearer"` | First-party session token |
+
+## OAuth2 ("Login with Manikineko")
+
+```python
+from manikineko import OAuth2Client, generate_pkce
+
+oauth = OAuth2Client(
+    base_url="https://api.manikineko.nl",
+    client_id="YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+    redirect_uri="https://myapp.example/callback",
+)
+
+verifier, challenge = generate_pkce()
+url = oauth.authorize_url(["identify", "email"], state=state, code_challenge=challenge)
+
+# In your callback handler:
+tokens = oauth.exchange_code(code, code_verifier=verifier)
+me = oauth.user(tokens["access_token"])          # GET /users/@me
+later = oauth.refresh_token(tokens["refresh_token"])
+oauth.revoke(tokens["access_token"])
+```
+
+`client_credentials` tokens (e.g. `scope="applications.gateway"`) call the
+app push API:
+
+```python
+tok = oauth.client_credentials("applications.gateway")
+app = Client(base_url, token=tok["access_token"], token_type="bearer")
+for server in app.app_servers():
+    app.app_send_message(server["id"], channel_id, "hello from my app")
+    app.app_dispatch_event(server["id"], "score_update", data={"score": 42})
+```
+
+## Gateway events
+
+Dispatch names mirror Discord: `READY`, `MESSAGE_CREATE`, `MESSAGE_UPDATE`,
+`MESSAGE_DELETE`, `CHANNEL_*`, `GUILD_*`, `GUILD_MEMBER_*`, `GUILD_ROLE_*`,
+`GUILD_BAN_*`, `MESSAGE_REACTION_*`, `PRESENCE_UPDATE`, `TYPING_START`,
+`INVITE_*`, `VOICE_STATE_UPDATE`. Manikineko extras: `APP_EVENT`,
+`URGENT_MESSAGE`, `WARNING_RECEIVED`, `USER_SUSPENDED`, `USER_BANNED`.
+
+```python
+@client.on("*")
+def log_all(payload):
+    print(payload["event"], payload["data"])
+```
+
+## Escape hatches
+
+```python
+client.request("GET", "/channels/123/messages")   # compat API
+client.api("GET", "/themes")                      # native /api/v1
+```
+
+## Errors
+
+`APIError` (`.status`, `.code`, `.body`), `OAuthError` (`.error`,
+`.error_description`), `InvalidSessionError` on bad gateway tokens.

manikineko-0.2.0/manikineko/__init__.py

@@ -0,0 +1,89 @@
+"""Official Python SDK for the Manikineko platform.
+
+Quickstart::
+
+    from manikineko import Client
+
+    client = Client(
+        base_url="https://api.manikineko.nl",
+        token="BOT_TOKEN",
+        token_type="bot",
+    )
+
+    @client.event
+    async def on_message_create(msg):
+        if msg.get("author", {}).get("bot"):
+            return
+        if msg.get("content") == "!ping":
+            client.say(msg["channel_id"], "pong")
+
+    client.run()
+"""
+
+from .admin import AdminAPI
+from .client import Client
+from .dialer import Dialer, PhoneCall
+from .errors import (
+    APIError,
+    InvalidSessionError,
+    ManikinekoError,
+    OAuthError,
+)
+from .gateway import Gateway
+from .oauth import OAuth2Client, generate_pkce, verify_gateway_signature
+from .types import (
+    ApplicationCommandOptionType,
+    ApplicationCommandType,
+    AutoModAction,
+    AutoModTrigger,
+    Capability,
+    ChannelType,
+    GatewayEvent,
+    GatewayOp,
+    InteractionCallbackType,
+    InteractionContextType,
+    InteractionType,
+    MessageFlags,
+    MessageType,
+    PrivilegeStatus,
+    RPCCommand,
+    RPCStatus,
+    Scope,
+    UserFlags,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Client",
+    "Gateway",
+    "OAuth2Client",
+    "Dialer",
+    "PhoneCall",
+    "AdminAPI",
+    "generate_pkce",
+    "verify_gateway_signature",
+    "ManikinekoError",
+    "APIError",
+    "OAuthError",
+    "InvalidSessionError",
+    "ChannelType",
+    "ApplicationCommandType",
+    "ApplicationCommandOptionType",
+    "InteractionType",
+    "InteractionCallbackType",
+    "InteractionContextType",
+    "MessageType",
+    "MessageFlags",
+    "GatewayOp",
+    "GatewayEvent",
+    "Capability",
+    "PrivilegeStatus",
+    "RPCCommand",
+    "RPCStatus",
+    "AutoModTrigger",
+    "AutoModAction",
+    "Scope",
+    "UserFlags",
+    "__version__",
+]