ETM-Schurig/powersync-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
powersync-docs/docs/api/metier/jsonrpc.md
Patrick Schurig 325409dd3f feat(i18n): prose traduite DE/EN et référence régénérée en anglais 
82 pages .de.md et 82 .en.md. La volumétrie explique la forme : 95 % du volume
est GÉNÉRÉ (74 013 mots contre 3 506 rédigés, mesuré sur 107 pages). On ne
traduisait donc pas 77 500 mots — on traduit la prose, et le vocabulaire des
générateurs fait le reste.

Prose traduite à la main : accueil, installation (4), fonctionnalités (4),
tarifs, référence, dépannage, FAQ, intégrations (2), api/index, et les 6 fiches
appareils qui portent une vraie prose + compatibilite.md. Les blocs générés ne
sont JAMAIS recopiés dans une traduction : le script de pose les reprend
verbatim du fichier français via des placeholders, pour qu'une traduction ne
puisse pas désynchroniser un bloc généré.

Les 49 fiches légères n'ont rien à traduire : leur tagline vient d'amont et est
DÉJÀ en anglais (« Connects nymea to powerfox. »). Constat, pas renoncement.

Localisation ≠ traduction, et tarifs.md en est l'exemple à connaître : la
version FR parle de Tempo et du signal RTE, la DE de §14a EnWG et de SMARD,
l'EN des deux. Ce ne sont pas des traductions l'une de l'autre, et c'est
volontaire — les signaux tarifaires sont nationaux. Aucune des deux n'est
annoncée comme livrée : les deux sont Roadmap, et les pages le disent.

Référence régénérée : en-têtes et libellés en anglais (Field/Type/Notes,
Supported models, Settings, Read-only, Brand / Model…). Conséquence assumée et
signalée : les pages FR en ligne changent aussi.

README.md (il était VIDE) : la règle du 95 % généré en tête, la frontière de
décision du multi-langue avec sa mesure, pourquoi SCAFFOLD existe, et le piège
--strict/navigation.instant.

TODO : multi-langue clos, et trois points ouverts qui en restent — les tagline
vivent dans les meta.json de 5 autres dépôts (forme à ajouter : tagline_de /
tagline_en), les stubs traduits restent des stubs (la dette éditoriale a triplé
en surface, pas en fond), api/types.md n'a pas besoin de variante. Le P1
openmeteo est corrigé sur constat : il EST dans PORTING_STATUS depuis, et une
ligne commentée contradictoire y traîne encore.

Vérifié : mkdocs build --strict vert sur les trois langues, 322 pages HTML,
contenu traduit relu dans le HTML produit, et les deux générateurs rendent
« Doc à jour » en --check.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-10-13 06:39:20 +02:00

211 lines
7.3 KiB
Markdown
Raw Blame History

# JSONRPC
<!-- BEGIN GENERATED: __api_JSONRPC__ -->
## Methods
### JSONRPC.Authenticate
<span class="badge perm-none">PUBLIC</span>
Authenticate a client to the api via user & password challenge. Provide a device name which allows the user to identify the client and revoke the token in case the device is lost or stolen. This will return a new token to be used to authorize a client at the API.
**Parameters:**
| Field | Type | Notes |
| --- | --- | --- |
| `deviceName` | `String` | |
| `password` | `String` | |
| `username` | `String` | |
**Returns:**
| Field | Type | Notes |
| --- | --- | --- |
| `scopes` | [PermissionScopes](../types.md#permissionscopes) | optional |
| `token` | `String` | optional |
| `username` | `String` | optional |
| `success` | `Bool` | |
---
### JSONRPC.CreateUser
<span class="badge perm-admin">ADMIN</span>
Create a new user in the API. This is only allowed to be called when the initial setup is required. To create additional users, use Users.CreateUser instead. Call Authenticate after this to obtain a device token for the newly created user.
**Parameters:**
| Field | Type | Notes |
| --- | --- | --- |
| `displayName` | `String` | optional |
| `email` | `String` | optional |
| `password` | `String` | |
| `username` | `String` | |
**Returns:**
| Field | Type | Notes |
| --- | --- | --- |
| `error` | [UserError](../types.md#usererror) | |
---
### JSONRPC.Hello
<span class="badge perm-none">PUBLIC</span>
Initiates a connection. Use this method to perform an initial handshake of the connection. Optionally, a parameter "locale" is can be passed to set up the used locale for this connection. Strings such as ThingClass displayNames etc will be localized to this locale. If this parameter is omitted, the default system locale (depending on the configuration) is used. The reply of this method contains information about this core instance such as version information, uuid and its name. The locale valueindicates the locale used for this connection. Note: This method can be called multiple times. The locale used in the last call for this connection will be used. Other values, like initialSetupRequired might change if the setup has been performed in the meantime.
The field cacheHashes may contain a map of methods and MD5 hashes. As long as the hash for a method does not change, a client may use a previously cached copy of the call instead of fetching the content again. While the Hello call doesn't necessarily require a token, this can be called with a token. If a token is provided, it will be verified and the reply contains information about the tokens validity and the user and permissions for the given token.
**Parameters:**
| Field | Type | Notes |
| --- | --- | --- |
| `locale` | `String` | optional |
**Returns:**
| Field | Type | Notes |
| --- | --- | --- |
| `authenticationRequired` | `Bool` | |
| `initialSetupRequired` | `Bool` | |
| `language` | `String` | |
| `locale` | `String` | |
| `name` | `String` | |
| `authenticated` | `Bool` | optional |
| `cacheHashes` | [CacheHash](../types.md#cachehash)[] | optional |
| `experiences` | [Experience](../types.md#experience)[] | optional |
| `permissionScopes` | [PermissionScopes](../types.md#permissionscopes) | optional |
| `username` | `String` | optional |
| `protocol version` | `String` | |
| `pushButtonAuthAvailable` | `Bool` | |
| `server` | `String` | |
| `uuid` | `Uuid` | |
| `version` | `String` | |
---
### JSONRPC.Introspect
<span class="badge perm-none">PUBLIC</span>
Introspect this API.
**Parameters:**
_No parameters._
**Returns:**
| Field | Type | Notes |
| --- | --- | --- |
| `methods` | `Object` | |
| `notifications` | `Object` | |
| `types` | `Object` | |
---
### JSONRPC.KeepAlive
<span class="badge perm-none">PUBLIC</span>
This is basically a Ping/Pong mechanism a client app may use to check server connectivity. Currently, the server does not actually do anything with this information and will return the call providing the given sessionId back to the caller. It is up to the client whether to use this or not and not required by the server to keep the connection alive.
**Parameters:**
| Field | Type | Notes |
| --- | --- | --- |
| `sessionId` | `String` | |
**Returns:**
| Field | Type | Notes |
| --- | --- | --- |
| `sessionId` | `String` | |
| `success` | `Bool` | |
---
### JSONRPC.RequestPushButtonAuth
<span class="badge perm-none">PUBLIC</span>
Authenticate a client to the api via Push Button method. Provide a device name which allows the user to identify the client and revoke the token in case the device is lost or stolen. If push button hardware is available, this will return with success and start listening for push button presses. When the push button is pressed, the PushButtonAuthFinished notification will be sent to the requesting client. The procedure will be cancelled when the connection is interrupted. If another client requests push button authentication while a procedure is still going on, the second call will take over and the first one will be notified by the PushButtonAuthFinished signal about the error. The application should make it clear to the user to not press the button when the procedure fails as this can happen for 2 reasons: a) a second user is trying to auth at the same time and only the currently active user should press the button or b) it might indicate an attacker trying to take over and snooping in for tokens.
**Parameters:**
| Field | Type | Notes |
| --- | --- | --- |
| `deviceName` | `String` | |
**Returns:**
| Field | Type | Notes |
| --- | --- | --- |
| `success` | `Bool` | |
| `transactionId` | `Int` | |
---
### JSONRPC.SetNotificationStatus
<span class="badge perm-none">PUBLIC</span>
Enable/Disable notifications for this connections. Either "enabled" or "namespaces" needs to be given but not both of them. The boolean based "enabled" parameter will enable/disable all notifications at once. If instead the list-based "namespaces" parameter is provided, all given namespaceswill be enabled, the others will be disabled. The return value of "success" will indicate success of the operation. The "enabled" property in the return value is deprecated and used for legacy compatibilty only. It will be set to true if at least one namespace has been enabled.
**Parameters:**
| Field | Type | Notes |
| --- | --- | --- |
| `d:o:enabled` | `Bool` | |
| `namespaces` | `StringList` | optional |
**Returns:**
| Field | Type | Notes |
| --- | --- | --- |
| `d:enabled` | `Bool` | |
| `namespaces` | `StringList` | |
---
### JSONRPC.Version
<span class="badge perm-none">PUBLIC</span>
Version of this nymea/JSONRPC interface.
**Parameters:**
_No parameters._
**Returns:**
| Field | Type | Notes |
| --- | --- | --- |
| `protocol version` | `String` | |
| `qtBuildVersion` | `String` | |
| `qtVersion` | `String` | |
| `version` | `String` | |
---
## Notifications
### JSONRPC.PushButtonAuthFinished
Emitted when a push button authentication reaches final state. NOTE: This notification is special. It will only be emitted to connections that did actively request a push button authentication, but also it will be emitted regardless of the notification settings.
**Parameters:**
| Field | Type | Notes |
| --- | --- | --- |
| `token` | `String` | optional |
| `success` | `Bool` | |
| `transactionId` | `Int` | |
---
<!-- END GENERATED -->
Reference in New Issue View Git Blame Copy Permalink