Skip to content

README.md

Latest commit

 

History

History
125 lines (95 loc) · 5.13 KB

README.md

File metadata and controls

125 lines (95 loc) · 5.13 KB
Raw

@onekeyfe/react-native-cloud-kit-module

CloudKit account and private-record access for OneKey apps on iOS.

npm license iOS Nitro Modules

Reads the iCloud account status and stores private records in the application's default CloudKit container. The module wraps the private database only — there is no public or shared database access. Records carry string data and meta payloads that the application serializes itself. Android compiles against the same interface but returns placeholder responses and stores nothing.

Features

  • Account awareness — isAvailable() and getAccountInfo() expose the CloudKit account status and the optional container user ID.
  • Private-record CRUD — save, fetch, delete and existence-check records by type and ID inside the app's private database.
  • Typed record queries — queryRecords() returns records for one type with stable result typing.
  • String payload boundary — data and meta are strings; the package never interprets or serializes application data.
  • Input validation — record types and IDs are validated before any CloudKit call, so malformed identifiers reject instead of creating odd records.
  • Timestamps in milliseconds — results expose createdAt/modifiedAt as numbers.

Installation

yarn add @onekeyfe/react-native-cloud-kit-module react-native-nitro-modules

Install the application's iOS pods and rebuild the native application; this is a Nitro module, so a JavaScript-only install does not register it. The iOS pod also links ReactNativeNativeLogger, so the application's pods must include @onekeyfe/react-native-native-logger.

The application must enable iCloud/CloudKit capabilities and provision the container used by CKContainer.default(); package installation does not grant CloudKit access. No Info.plist usage-description key is required.

Usage

import { CloudKit } from '@onekeyfe/react-native-cloud-kit-module';

if (await CloudKit.isAvailable()) {
  const account = await CloudKit.getAccountInfo();

  await CloudKit.saveRecord({
    recordType: 'Backup',
    recordID: 'example-record',
    data: JSON.stringify({ version: 1 }),
    meta: JSON.stringify({ createdAt: Date.now() }),
  });

  const record = await CloudKit.fetchRecord({
    recordType: 'Backup',
    recordID: 'example-record',
  });
}

The caller owns the record schema, serialization format and which application data is allowed to leave the device for iCloud.

API

Method Result Platforms Description
isAvailable() Promise<boolean> iOS true when the CloudKit account status is available.
getAccountInfo() Promise<AccountInfoResult> iOS Account status, statusName and optional containerUserId.
saveRecord(params) Promise<SaveRecordResult> iOS Saves { recordType, recordID, data, meta } and returns recordID + createdAt.
fetchRecord(params) Promise<RecordResult | null> iOS Reads a record or resolves null.
deleteRecord(params) Promise<void> iOS Deletes a record in the private database.
recordExists(params) Promise<boolean> iOS Checks for a record by type and ID.
queryRecords(params) Promise<QueryRecordsResult> iOS Returns { records } for one record type.

SaveRecordParams, RecordResult, AccountInfoResult, QueryRecordsResult and the other parameter types are exported for adapters. See src/CloudKitModule.nitro.ts.

Platform support

Capability iOS Android Web
Check CloudKit availability/account ✅ — —
Save/fetch/delete private records ✅ — —
Record existence check ✅ — —
Query records by type ✅ — —

Caveats

Important

This is an iOS-only module. On Android every method returns a placeholder — false, null, an empty record or a zeroed result — without persisting anything. Never treat a placeholder write as a successful iCloud backup.

Warning

The application must configure its iCloud/CloudKit entitlement and the container used by CKContainer.default(). Availability, a successful write and later retrieval are separate checks; handle CloudKit rejections in the application.

Note

queryRecords() returns at most 200 records and fetches only the meta field, so data is empty for query results — fetch each record for its payload. Record types must match ^[a-zA-Z][a-zA-Z0-9_]{0,254}$ and record IDs must be 1–255 characters.

References

License

MIT. See LICENSE.