Skip to content
calternal docs

calternal-api

DTOs shared by the server and API clients.

Cursor values are opaque continuation tokens. Clients pass them back without reading or changing them. A missing next cursor means that a page is final. API timestamps use RFC 3339 with a UTC offset (Z). Shared byte-range parsing keeps generated download continuations bounded (#760).

Source: crates/calternal-api/src/lib.rs

Modules

Section titled “Modules”
Module Summary
actions Contract action metadata and request mapping (#484, #760, #818, #821, DESIGN §41).
http_failure Typed HTTP failures shared by client surfaces (#835, DESIGN §41).
public_address Shared public-address classification for outbound requests (#431, #726).
events Draft webhook contracts from the shared action registry (DESIGN §55).

Re-exports

Section titled “Re-exports”

Structs

Section titled “Structs”

ApiError

Section titled “ApiError”
pub struct ApiError

The error object inside the API error envelope.

Fields

  • pub code: ErrorCode: Stable machine-readable code.
  • pub message: String: Safe text for logs or a user-facing error message.
  • pub details: Option<ErrorDetails>: Optional field or operation details.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:98

CommandAction

Section titled “CommandAction”
pub struct CommandAction

A command-palette action contributed by a plugin.

Fields

  • pub id: String: Stable action identifier within the plugin.
  • pub title: String: Action label.
  • pub description: Option<String>: Optional short explanation.
  • pub shortcut: Option<String>: Optional keyboard shortcut shown by the client.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:189

CursorPage

Section titled “CursorPage”
pub struct CursorPage<T>

A cursor page. Cursor values are opaque to clients.

Fields

  • pub items: Vec<T>: Items in this page.
  • pub next_cursor: Option<String>: Cursor for the next page, if one exists.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:408

ErrorEnvelope

Section titled “ErrorEnvelope”
pub struct ErrorEnvelope

The standard API error response: { "error": { ... } }.

Fields

  • pub error: ApiError: Error details.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

ErrorEnvelope::new

Section titled “ErrorEnvelope::new”
pub fn new(code: ErrorCode, message: impl Into<String>) -> Self

Create an error envelope without extra details.

Source: crates/calternal-api/src/lib.rs:110

ParsedSearchQuery

Section titled “ParsedSearchQuery”
pub struct ParsedSearchQuery

The parsed form of a search query. This shape is the cross-client contract for operators; clients can use it to render removable filter pills.

Fields

  • pub terms: Vec<String>: Plain words and quoted phrases, in query order.
  • pub filters: Vec<SearchFilter>: Filters in query order. Repeated filters are preserved.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:309

PluginCatalog

Section titled “PluginCatalog”
pub struct PluginCatalog

The plugin catalog returned to the SPA, including disabled plugins.

Fields

  • pub plugins: Vec<PluginDescriptor>: Plugin descriptors in stable ID order.

Implements: Clone, Debug, Default, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:226

PluginDescriptor

Section titled “PluginDescriptor”
pub struct PluginDescriptor

A plugin manifest with the current enablement state and client data.

Fields

  • pub manifest: PluginManifest: The plugin’s public manifest.
  • pub enabled: bool: Whether an administrator enabled this plugin for the Instance.
  • pub user_enabled: Option<bool>: This User’s mode state, or None when no user toggle applies.
  • pub ui: PluginUiEntryPoints: UI entry points available to the current user.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:213

PluginManifest

Section titled “PluginManifest”
pub struct PluginManifest

Public metadata declared by a plugin.

Fields

  • pub id: String: Stable lowercase identifier used in API paths.
  • pub name: String: Human-readable plugin name.
  • pub version: String: Plugin version.
  • pub description: String: Short description.
  • pub kind: PluginKind: Plugin origin.
  • pub core: bool: True when this plugin is required by the instance and cannot be disabled.
  • pub default_enabled: bool: Enable the plugin for a new instance unless an administrator changes it.
  • pub user_toggle_allowed: bool: Allow each user to hide this plugin when it is enabled for the instance.
  • pub requires: Vec<String>: Other plugins that must be enabled before this plugin can run.
  • pub required_scopes: Vec<String>: Scopes a client needs to call this plugin’s routes.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:140

PluginRoute

Section titled “PluginRoute”
pub struct PluginRoute

A client route contributed by a plugin.

Fields

  • pub id: String: Stable route identifier within the plugin.
  • pub path: String: SPA route pattern.
  • pub title: String: Human-readable route title.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:178

PluginUiEntryPoints

Section titled “PluginUiEntryPoints”
pub struct PluginUiEntryPoints

All user-interface entry points declared by a plugin.

Fields

  • pub sidebar: Vec<SidebarEntry>: Sidebar entries.
  • pub routes: Vec<PluginRoute>: SPA routes.
  • pub actions: Vec<CommandAction>: Command-palette actions.

Implements: Clone, Debug, Default, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:202

SavedSearch

Section titled “SavedSearch”
pub struct SavedSearch

A saved search: a named query that works like a smart folder (DESIGN §32 S10). It is user data, stored as one JSON file per search in <home>/.calternal/saved-searches/<id>.json.

Fields

  • pub id: String: Stable identifier (a lowercase UUID). Links use it, so a rename never breaks them.
  • pub name: String: Display name chosen by the user.
  • pub query: String: The raw query, operators included, exactly as the search field shows it.
  • pub pinned: bool: True when the search shows in the sidebar.
  • pub created: String: Creation time (RFC 3339, UTC).
  • pub updated: String: Last change time (RFC 3339, UTC).

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:362

SavedSearchInput

Section titled “SavedSearchInput”
pub struct SavedSearchInput

Input to create a saved search.

Fields

  • pub name: String: Display name (1 to 120 characters).
  • pub query: String: Raw query with operators (1 to 512 characters, valid search grammar).
  • pub pinned: bool: Show the search in the sidebar. Default: false.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:381

SavedSearchPatch

Section titled “SavedSearchPatch”
pub struct SavedSearchPatch

Changes to a saved search. Omitted fields stay the same.

Fields

  • pub name: Option<String>: New display name.
  • pub query: Option<String>: New raw query.
  • pub pinned: Option<bool>: New sidebar state.

Implements: Clone, Debug, Default, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:394

SearchHit

Section titled “SearchHit”
pub struct SearchHit

A single result from a server-side plugin search provider.

Fields

  • pub plugin_id: String: Plugin that owns the result.
  • pub id: String: Stable result identifier within the plugin.
  • pub title: String: Main result label.
  • pub snippet: Option<String>: Optional preview text.
  • pub href: String: Client route for opening the result.
  • pub score: Option<f32>: Optional provider relevance score. Clients must not compare scores from different providers as if they shared one scale.
  • pub kind: Option<String>: Optional result kind from the search grammar (note, task, log, photo, bookmark, text, file, folder, event). Clients group and facet results by it; a missing kind means the provider does not know it.
  • pub path: Option<String>: Optional Home-relative client path of the object (for example Files/plan.pdf, or Shared/<owner>/… for a Share). Clients use it for thumbnails, previews and folder facets.
  • pub mime: Option<String>: Optional media/document MIME type used to render file results consistently.
  • pub modified: Option<i64>: Optional last-modified time (or the day of a log entry) in Unix seconds.
  • pub tags: Option<Vec<String>>: Ordered Event categories. Calendar clients use the first tag for tint.

Implements: Clone, Debug, Default, Deserialize, PartialEq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:244

SearchIndexStatus

Section titled “SearchIndexStatus”
pub struct SearchIndexStatus

Search index work that is running while the current Index remains queryable.

Fields

  • pub indexing: bool: True while the Index is being scanned or repaired.
  • pub progress_percent: Option<u8>: Percentage of searchable paths scanned, when the scan size is known.
  • pub completed_items: u64: Searchable paths scanned in the current pass.
  • pub total_items: Option<u64>: Total searchable paths in the current pass, when known.

Implements: Clone, Debug, Default, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:281

SearchResponse

Section titled “SearchResponse”
pub struct SearchResponse

Results from the server-side search fan-out.

Fields

  • pub results: Vec<SearchHit>: Search hits returned by providers that completed before the deadline.
  • pub timed_out: bool: True when the request deadline stopped one or more providers.
  • pub indexing: Option<SearchIndexStatus>: Search index progress, when an Index is available.

Implements: Clone, Debug, Default, Deserialize, PartialEq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:296

SidebarEntry

Section titled “SidebarEntry”
pub struct SidebarEntry

A sidebar entry contributed by a plugin.

Fields

  • pub id: String: Stable entry identifier within the plugin.
  • pub title: String: Text shown in the sidebar.
  • pub icon: Option<String>: Optional icon name understood by the client.
  • pub href: String: Client route opened by this entry.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:165

SystemInfo

Section titled “SystemInfo”
pub struct SystemInfo

Instance metadata returned by the system plugin.

Fields

  • pub version: String: Server release version.
  • pub commit: String: Source commit hash, or unknown when the build did not provide one.
  • pub instance_name: String: Display name of this instance.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:233

Enums

Section titled “Enums”

ByteRangeError

Section titled “ByteRangeError”
pub enum ByteRangeError

Why a byte range cannot be served.

Variants

  • Malformed: The Range value does not contain one valid byte range.
  • NotSatisfiable: The requested byte range does not overlap the representation.

Implements: Clone, Copy, Debug, Eq, PartialEq

Source: crates/calternal-api/src/lib.rs:14

ErrorCode

Section titled “ErrorCode”
pub enum ErrorCode

A stable error identifier for an API response.

Variants

  • BadRequest: The request is malformed or has invalid values.
  • Unauthorized: The request has no valid authentication.
  • Forbidden: The authenticated user lacks the required authority.
  • NotFound: The requested object does not exist.
  • Conflict: The request conflicts with current server state.
  • NameConflictCase: A sibling has the same NFC and Unicode case-folded name.
  • NameTooLong: A filename or relative path exceeds the supported byte limit.
  • PushEndpointRejected: A browser push endpoint violates the outbound destination policy.
  • TooManyRequests: The request exceeded a rate limit.
  • Internal: The server could not complete the request.
  • ServiceUnavailable: The requested service is temporarily unavailable.

Implements: Clone, Copy, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:68

PluginKind

Section titled “PluginKind”
pub enum PluginKind

Whether a plugin is part of the binary or comes from an external source.

Variants

  • Core: Compiled into the server.
  • Community: Loaded from an external source. Runtime loading comes later.

Implements: Clone, Copy, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:131

SearchFilter

Section titled “SearchFilter”
pub enum SearchFilter

One parsed search operator.

Variants

  • Tag { value: String }: A tag that must match exactly.
  • Type { value: String }: A result type from the search grammar.
  • Date { value: String }: An absolute or natural date expression.
  • In { value: String }: A path relative to one of the caller’s allowed roots.
  • Is { value: String }: A result state such as todo, done, shared, favorite, or a Notes link-health state.
  • From { value: String }: A person who created the result.
  • With { value: String }: A person associated with the result.
  • Extension { value: String }: A file extension without a leading dot.
  • Size { comparison: SearchSizeComparison, bytes: u64, }: A file-size comparison in bytes.
  • Has { value: String }: A result with a selected content kind or Notes reference form.

Implements: Clone, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:319

SearchSizeComparison

Section titled “SearchSizeComparison”
pub enum SearchSizeComparison

Direction for a size filter.

Variants

  • GreaterThan: Match sizes greater than the value.
  • LessThan: Match sizes less than the value.

Implements: Clone, Copy, Debug, Deserialize, PartialEq, Eq, Serialize, ToSchema

Source: crates/calternal-api/src/lib.rs:351

Type aliases

Section titled “Type aliases”

ErrorDetails

Section titled “ErrorDetails”
pub type ErrorDetails = BTreeMap<String, String>;

Error details. Values are short strings that do not expose server secrets.

Source: crates/calternal-api/src/lib.rs:94

Functions

Section titled “Functions”

parse_byte_range

Section titled “parse_byte_range”
pub fn parse_byte_range(value: &str, size: u64) -> Result<(u64, u64), ByteRangeError>

Parse one HTTP byte range shared by binary API routes (#760).

Multiple ranges are rejected so callers cannot multiply work or memory by asking one generated action for an unbounded multipart response.

Source: crates/calternal-api/src/lib.rs:25