Gusnais Skill

Implement Gusnais API integration that mirrors web behavior and permission boundaries.

Require only two user inputs

• - INLINECODE0
• INLINECODE1

Do not ask for base URL, OAuth paths, account IDs, scope defaults, pagination defaults, or serializer mappings unless discovery fails.

Auto-complete platform config

Use these defaults:

• - Site: INLINECODE2
• OAuth Authorize: INLINECODE3
• OAuth Token: INLINECODE4
• OAuth Revoke: INLINECODE5
• API Base: INLINECODE6

Auth flow

1. 1. Build authorization URL automatically.
2. Exchange authorization code for access_token and refresh_token.
3. Validate token with GET /api/v3/users/me.
4. Refresh once on 401; if refresh fails, request re-auth.

Prefer Authorization header for requests:

• - INLINECODE10

Keep access_token query fallback for compatibility with Homeland API behavior.

Web parity contract

Match gusnais.com UX and permission behavior:

1. 1. Read abilities first when available

- Resource-level actions must follow returned abilities.

1. 2. Dual check

- UI check (visible/enabled) using abilities. - Execution check with real API call and status code handling.

1. 3. No privilege escalation

- Never assume admin/mod privileges in client logic.

1. 4. Respect hidden/inaccessible resources

- 404/403 semantics should stay consistent with server behavior.

Capability gating model

For each action produce:

• - visible: INLINECODE14
• INLINECODE15: INLINECODE16
• INLINECODE17: INLINECODE18
• INLINECODE19: INLINECODE20

Endpoint behavior alignment

Use endpoint mapping in references/endpoints.md and serializer notes for normalized outputs.

Keep defaults aligned with docs:

• - offset default: INLINECODE22
• limit default: INLINECODE23
• limit range on list endpoints: 1..150 (or endpoint-specific documented max)
• topic list default INLINECODE25

For plugin domain operations (press/note/site/jobs):

• - Read plugin web-route parity and API contract in references/endpoints.md.
• Read permission nuances in references/permission-parity.md.
• Treat 404 on plugin API endpoints as resource_unavailable unless deployment has enabled those API routes.

Topic action safety

For POST /api/v3/topics/:id/action?type=:type (ban|excellent|unexcellent|close|open):

• - Gate by abilities if present.
• Enforce final server response.
• Never expose action as enabled when denied.

Error mapping

Normalize API errors without changing meaning:

• - 400 -> INLINECODE32
• 401 -> auth_required (refresh then retry once)
• 403 -> INLINECODE34
• 404 -> INLINECODE35
• 500 -> INLINECODE36

Return original server error text when available.

Rate limiting / retries

• - Respect Retry-After on 429.
• Use exponential backoff with jitter for transient 5xx.
• Avoid one-item tight loops for batch writes.

Read these references before implementation

• - INLINECODE38
• INLINECODE39

Bootstrap script

Use scripts/gusnais_bootstrap.py to initialize runtime config from CLIENT_ID and CLIENT_SECRET.

Recommended:

• - set TOKEN_STORE_PATH when exchanging code, so refreshable tokens are persisted to JSON for long-lived automation.

Plugin API client script

Use scripts/gusnais_plugin_client.py for plugin API read/write calls with:

• - auto refresh before expiry and on 401;
• one retry after refresh;
• normalized status reason mapping;
• capability hint extraction from abilities;
• action-level payload guardrails to avoid avoidable 400/500 (e.g. press create summary fallback).

Current deployment notes (2026-03-19):

• - Press API is mounted for read/write (/api/v3/press/posts*).
• Note API is mounted for read/write (/api/v3/note/notes*).
• Site API is mounted for sites CRUD + site_nodes list; undestroy/site_node writes are not mounted.
• Treat any unmounted plugin API route as resource_unavailable and avoid repeated retries.