cloudkit

Safe Rust bindings for Apple's CloudKit framework on macOS.

Status: v0.2.0 broadens the bridge from the initial container/database surface to per-area coverage for container, database, record, record ID, zone, subscription, operation, share, notification info, query, fetched results, reference utility, server change token, asset, and user identity APIs. See COVERAGE.md for the audited SDK/header-to-source map.

Quick start

use cloudkit::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut record = CKRecord::new("Task")?;
    record.set_object("title", "Ship v0.2.0");
    record.set_object("done", false);

    let share = CKShare::new_root_record(&record)?;
    println!(
        "record_type={} share_record_type={} participants={}",
        record.record_type(),
        share.share_record().record_type(),
        share.participants().len()
    );
    Ok(())
}

Highlights

• CKContainer default/custom containers, account status, user-record lookup, user-identity discovery, and share-participant lookup
• CKDatabase record CRUD, first-batch query helpers, fetched query results, record-zone helpers, and subscription helpers
• Value-layer Rust wrappers for CKRecord, CKRecordID, CKRecordZone, CKAsset, CKReference, CKNotificationInfo, CKServerChangeToken, CKUserIdentity, and CKShare
• Operation builders for CKModifyRecordsOperation, CKQueryOperation, CKFetchRecordsOperation, CKFetchDatabaseChangesOperation, and CKFetchRecordZoneChangesOperation
• Headless numbered examples 01–15 plus per-area integration tests

Validation

The v0.2.0 bridge is validated with:

cargo clippy --all-targets -- -D warnings
cargo test
for ex in examples/*.rs; do cargo run --example "$(basename "$ex" .rs)"; done

Entitlements / caveats

CloudKit requires an entitled app plus an iCloud account for most server-backed operations. Unsigned CLI binaries commonly hit CKErrorMissingEntitlement, CKErrorBadContainer, or CKErrorNotAuthenticated. When CKContainer::default() cannot be resolved because the current process has no iCloud container entitlement, the crate surfaces a bridge error instead of letting CloudKit raise an Objective-C exception. Headless tests and examples can therefore report entitlement/account limitations gracefully instead of crashing.

Examples

Run the defensive framework smoke test with:

cargo run --example 01_account_status_smoke

Other numbered examples cover the expanded logical areas:

• 02_database_zones_and_subscriptions
• 03_record_value_roundtrip
• 04_record_id_construction
• 05_zone_construction
• 06_subscription_builders
• 07_operation_builders
• 08_share_local_construction
• 09_notification_info_builder
• 10_query_builder
• 11_fetched_results_smoke
• 12_reference_utility
• 13_server_change_token_bytes
• 14_asset_file_url
• 15_user_identity_lookup

License

Licensed under either Apache-2.0 or MIT at your option.