Skip to main content

UserPluginDto

User plugin instance status

autoSyncbooleanrequired

Whether this connection is opted into automatic scheduled syncs (host-side preference, derived from config._codex.autoSync). When false (the default), syncs run only when manually triggered.

capabilities objectrequired

Plugin capabilities (derived from manifest)

readSyncbooleanrequired

Can sync reading progress

userRecommendationProviderbooleanrequired

Can provide recommendations

wantsDetailedProgressbooleanrequired

Consumes the per-book reading-progress breakdown (readBooks); when set, the host attaches per-book volume/chapter/page detail to sync entries.

wantsFullMetadatabooleanrequired

Consumes enriched series data (tags/genres/bibliographic block, and admin-permitted custom metadata) on the entries the host sends.

configrequired

Per-user configuration

connectedbooleanrequired

Whether the plugin is connected and ready to operate. True when the plugin has valid credentials/OAuth, or when it requires no per-user authentication (credential-less or shared-key plugins).

createdAtstring<date-time>required

Created timestamp

descriptionstring | nullnullable

User-facing description of the plugin

enabledbooleanrequired

Whether the user has enabled this plugin

externalAvatarUrlstring | nullnullable

External service avatar URL

externalUsernamestring | nullnullable

External service username (if connected via OAuth)

healthStatusstringrequired

Health status of this user's plugin instance

idstring<uuid>required

User plugin instance ID

lastSuccessAtstring,null<date-time>nullable

Last successful operation timestamp

lastSyncAtstring,null<date-time>nullable

Last sync timestamp

lastSyncResult

Last sync result summary (stored in user_plugin_data)

oauthConfiguredbooleanrequired

Whether the admin has configured OAuth credentials (client_id set)

pluginDisplayNamestringrequired

Plugin display name for UI

pluginIdstring<uuid>required

Plugin definition ID

pluginNamestringrequired

Plugin display name

pluginTypestringrequired

Plugin type: "system" or "user"

requiresAuthbooleanrequired

Whether this plugin requires per-user authentication (OAuth or required credentials). When false, the connect/disconnect flow is not applicable; the plugin is usable as soon as it is enabled.

requiresOauthbooleanrequired

Whether this plugin requires OAuth authentication

syncCronSchedulestring | nullnullable

The admin-configured cron schedule that drives automatic syncs for this plugin (the normalized 6-field form), or None when the admin has not set one. Surfaced read-only so the UI can show the cadence to users and indicate when auto sync isn't set up yet. The cadence is plugin-wide, not per-user.

userConfigSchema object

User-facing configuration schema (from plugin manifest)

descriptionstring | nullnullable

Human-readable description of the configuration

fields object[]required

List of configuration fields

  • Array [
    • default

    Default value if not provided

    descriptionstring | nullnullable

    Description of what this field does

    example

    Example value for documentation

    keystringrequired

    Field name (key in JSON config)

    labelstringrequired

    Human-readable label

    requiredboolean

    Whether this field is required

    typestringrequired

    Field type — free-form documentation hint. Common values: "number", "string", "boolean", "string-array", "object". The host never validates stored config against this; it forwards the raw JSON to the plugin.

  • ]
    • userSetupInstructionsstring | nullnullable

    User-facing setup instructions for the plugin

    UserPluginDto
    {
      "autoSync": true,
      "capabilities": {
        "readSync": true,
        "userRecommendationProvider": true,
        "wantsDetailedProgress": true,
        "wantsFullMetadata": true
      },
      "connected": true,
      "createdAt": "2024-07-29T15:51:28.071Z",
      "description": "string",
      "enabled": true,
      "externalAvatarUrl": "string",
      "externalUsername": "string",
      "healthStatus": "string",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "lastSuccessAt": "2024-07-29T15:51:28.071Z",
      "lastSyncAt": "2024-07-29T15:51:28.071Z",
      "oauthConfigured": true,
      "pluginDisplayName": "string",
      "pluginId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "pluginName": "string",
      "pluginType": "string",
      "requiresAuth": true,
      "requiresOauth": true,
      "syncCronSchedule": "string",
      "userConfigSchema": {
        "description": "string",
        "fields": [
          {
            "description": "string",
            "key": "string",
            "label": "string",
            "required": true,
            "type": "string"
          }
        ]
      },
      "userSetupInstructions": "string"
    }