pigway-frame-flow/docs/research/KOKONNA_ACCOUNT_CAPABILITIES.md

# KoKonna official account capabilities

Reviewed 2026-10-03. Source: official Android nightly 1.6.5 client, downloaded
from https://kokonna.art/pages/download-app. RPC method names and usage were
inspected without running or modifying the app. No vendor source is distributed.

## Two independent access paths

Frame Flow retains its existing device API Key integration. The documented
OpenAPI provides device status, upload, image listing/download/delete and display
selection by ID/name. It exposes rotation, timezone and automatic image-change
status as read fields, but does not document setters for them.

Account login accesses the official RPC service. The current device key was
explicitly tested against device discovery and widget discovery: both rejected
it with `请重新登陆`. Account login, device discovery/detail and widget discovery
have been verified successfully with HTTP 200. Other methods below are found in
client code only: their availability, permissions and side effects have not been
live-tested. Missing OpenAPI documentation is not proof that no undocumented
API Key endpoint exists.

## Additional frame-related capabilities found

| Capability | RPC methods | Evidence and boundary |
| --- | --- | --- |
| Official widgets and parameters | getFrameCovers / setFrameCover | Catalog read verified (75 items); current selection can be empty. Selection/cancellation discovered, not tested. |
| Rotation configuration | setRotate | Discovered setter; OpenAPI only reads rotation. |
| Device name and timezone | changeName / app.setTimezone | Discovered setters; OpenAPI only reads these fields. |
| Slideshow mode and period | setFrameImageChangeType / setFrameImageChangeMinute | Discovered setters; actual rotation sequence must be derived from mode/filter/order, not invented. |
| Slideshow tag filters | setFrameImageChangeTags | Discovered filter configuration. |
| Tagged, paginated image library | getImages / addTag / removeTag / setImageTags | Discovered; original client passes `page`, `paegSize` (spelling as observed) and `tags`. Requires separate validation. |
| Image renaming | changeFrameImageName | Discovered; distinct from rename-device. |
| Official gallery collections | getFrameGallerys / getFrameGalleryImages / addFrameGalleryImage | Discovered browse/add flow; may depend on entitlement. |
| Artist content | getFrameArtists / addFrameArtist | Discovered; subscriptions/selection may consume points or alter display. |
| Startup/splash image | getFrameSplashs / setSplash | Discovered browse/set flow. |
| Remote refresh | refreshImage | Discovered write; do not infer display success from RPC acceptance. |
| Image sharing/import | getShareImages / shareImage / importImagesByTransferToken | Discovered; do not expose transfer tokens or share credentials. |
| Device sharing and pairing | enablePair / enableShareCode / refreshShareUUID; app.addShareRobot / removeShare | Discovered sensitive configuration; excluded from automatic tests. |
| Firmware information/upgrade | app.getFirmwares / setUpgradeFirmware | Discovered; not enabled or tested. |
| Wake/sleep interval | setFrameImageChangeInterval | Client updates `defaultSleepTime`; do not mistake this for slideshow minutes. |
| AI/voice content | chat / recognizeVoice / text2speech | Discovered; support may vary with hardware, service and account credits. |
| Feedback and likes | reportFrameImage / likeImage | Discovered; modifies remote account data. |

RPC methods in this table use the `appFrame.` prefix unless explicitly `app.`.
Generic account methods also cover profile, password, device binding/unlinking,
credits/orders and custom assistant roles. Their presence in the shared client
is not evidence that all are supported by the 13.3-inch B101 frame. No binding,
reset, firmware, payment or subscription mutation was executed during research.

## Frame Flow implementation boundary

- API Key device/gallery/upload/display support remains unchanged.
- Official widget panel separately explains account authorization requirements.
- The existing WidgetReader uses a server-side official session secret; admin
  account/password connection UI is implemented; automatic session renewal is not.
- Live `NO_WIDGET` requires explicit null current-widget association and null
  robot association ID; missing fields remain `CURRENT_UNVERIFIED`.
- Unconfigured access returns `AUTH_REQUIRED` and an explicitly dated snapshot.
- Widget selection and the other RPC writes above are not implemented. Account
  login capability discovery is not permission to exercise those writes.

## Module extraction

Official capabilities now live in `pigway_frame_flow/integrations/kokonna_official/`.
The account RPC client, login/session handling, operation inventory and widget
normalization/catalog are isolated there. API Key drivers no longer own a widget
reader. DeviceRegistry composes the optional integration separately per device;
the existing public widget route and old Python import remain compatible.
Only login and the three verified reads are enabled. The module has no generic
public RPC execution endpoint, and unenabled methods cannot reach the network.