skrzynka sync

Invocation#

skrzynka --organization <ID> sync [--mailbox <MAILBOX>]

Purpose#

Read which items Skarbiec declares, then import every new message for one mailbox or for every declared mailbox.

Inputs and options#

Global options accepted on this path are --organization <ID> (required on every command except serve, version and onboarding; none is assumed), --skarbiec-bin <PATH> (default skarbiec) and --text (print results as path: value lines for people instead of JSON).

Output and state effect#

With --mailbox, resolves that mailbox's credential, imports every unseen IMAP UID, committing each message with the cursor past it, and prints {mailbox_id, received, skipped, last_uid, completed_at}. Without --mailbox, first reconciles with Skarbiec and prints {completed_at, reconciliation, mailboxes:[...]}: reconciliation holds declared, created, updated, undeclared, and refused (each {skarbiec_item_id, code, message}); each mailbox carries ok, a summary, or normalized error fields. Undeclared mailboxes are skipped. One mailbox failure is recorded on its row and embedded in the result while the command continues and exits 0.

Refusals#

• Invalid UUID syntax is refused by Clap before dispatch with exit 2. With --mailbox, NOT_FOUND: mailbox was not found.
• Without --mailbox, a vault that cannot be listed refuses the whole pass with SKARBIEC_UNAVAILABLE, SKARBIEC_TIMEOUT, or SKARBIEC_RESPONSE_INVALID. A declared item whose profile is invalid is a reconciliation.refused entry, not a refusal.
• Credential failures are refused for a single mailbox as SKARBIEC_ITEM_INVALID, SKARBIEC_UNAVAILABLE, SKARBIEC_TIMEOUT, or SKARBIEC_RESPONSE_INVALID.
• Provider failures retain the actual operation and cause: IMAP_UNAVAILABLE names TLS connect and host/port; IMAP_AUTHENTICATION_FAILED names XOAUTH2 or LOGIN and the observed refusal or transport failure; IMAP_INBOX_UNAVAILABLE names SELECT INBOX; IMAP_SEARCH_FAILED names the starting UID; IMAP_FETCH_FAILED names the requested UID. Supplied authentication secrets are redacted. Worker-task failures name the mailbox and retain the task cause instead of claiming a provider refusal.
• When writing the failure to mailbox state also fails, the live refusal retains its original code and cause and appends the recording failure. Worker-task failures use the same persistence path. The watcher logs both errors; a previously stored last_error_message is not evidence that the current failure was recorded.
• Without --mailbox, per-mailbox failures are result entries, not whole-command refusals; callers must inspect every ok value.