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; gates whether the _codex.send* metadata toggles are shown on the connection.

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

sendCustomMetadatabooleanrequired

User privacy opt-out for sending user-defined custom metadata (host-side, from config._codex.sendCustomMetadata). Default false. tags/genres/the bibliographic block are admin policy on the plugin, not user-controlled.

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
oneOf
null
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,
  "sendCustomMetadata": true,
  "syncCronSchedule": "string",
  "userConfigSchema": "null",
  "userSetupInstructions": "string"
}