@expo-kit/cloudkit 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+# @expo-kit/cloudkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed iCloud sync for Expo apps. Your app keeps its own database; this package syncs its records between the user's devices through their private iCloud, using Apple's `CKSyncEngine` in Swift. Part of expo-kit, small packages for Expo apps. Not made by Expo or Apple.
+
+- Works with any data: you describe your records once in TypeScript, and every call is typed from that.
+- Native Swift on JSI (Expo Modules API), no old bridge.
+- Offline-safe: changes wait on the device (in the module's own SQLite file) and upload later, also after the app was killed.
+- A fresh install downloads first, so it never overwrites what's already in iCloud.
+- Files (assets) keep their file type.
+
+iOS 17+ only. Needs a development build (not Expo Go).
+
+## Install
+
+```sh
+npx expo install @expo-kit/cloudkit expo-build-properties
+```
+
+`app.json`:
+
+```json
+{
+  "expo": {
+    "ios": { "bundleIdentifier": "com.example.app" },
+    "plugins": [
+      ["@expo-kit/cloudkit", { "containers": ["iCloud.com.example.app"] }],
+      ["expo-build-properties", { "ios": { "enableSceneSupport": true } }]
+    ]
+  }
+}
+```
+
+- The plugin adds the iCloud entitlements, background pushes, and sets iOS 17 as the minimum.
+- `enableSceneSupport` is needed for Expo SDK 57 apps built with Xcode 27 (the app crashes at launch without it). SDK 58+ doesn't need it.
+- The first signed build registers the container on your Apple team (Xcode automatic signing does this).
+
+## 1. Describe the data
+
+```ts
+import { defineCloudSchema, field, type CloudRecord } from '@expo-kit/cloudkit';
+
+export const schema = defineCloudSchema({
+  Venue: { name: field.string() },
+  Shift: {
+    date: field.date(),
+    tips: field.double(),
+    hours: field.int(),
+    paid: field.bool(),
+    note: field.string().optional(),
+    tags: field.stringList(),
+    venue: field.reference('Venue'),
+    photo: field.asset().optional(),
+  },
+});
+
+export type Shift = CloudRecord<typeof schema, 'Shift'>;
+// { id: string; date: Date; tips: number; hours: number; paid: boolean; tags: string[]; venue: string;
+//   note?: string | null; photo?: string | null }
+```
+
+Field kinds: `string`, `int`, `double`, `bool`, `date`, `stringList`, `intList`, `doubleList`, `reference(type)` (the linked record's `id`), `asset` (a local file path). Add `.optional()` for a field that can be empty.
+
+Every record has a string `id`, unique within its type (ASCII). After release, only **add** types and fields; never rename or remove one.
+
+## 2. Connect your database
+
+```ts
+import { createCloudSync } from '@expo-kit/cloudkit';
+
+export const sync = createCloudSync({
+  container: 'iCloud.com.example.app',
+  schema,
+  apply: {
+    // Changes from other devices. Insert-or-update, and delete.
+    Shift: { save: (shifts) => db.upsertShifts(shifts), delete: (ids) => db.deleteShifts(ids) },
+    Venue: { save: (venues) => db.upsertVenues(venues), delete: (ids) => db.deleteVenues(ids) },
+  },
+  conflict: 'newest', // or 'server' | 'device'
+  onAccountChange: ({ change }) => {
+    // 'signOut' | 'switchAccounts' | 'cloudDataDeleted': sync state was reset.
+    // Keep or clear local data; to upload it to the new account, call importAll.
+  },
+});
+
+// Once, when the app's database is ready:
+await sync.start();
+```
+
+`apply` handlers may throw (e.g. a foreign key isn't there yet): that group is retried after the others, and nothing is lost.
+
+## 3. Tell it about your own writes
+
+```ts
+await db.insertShift(shift);
+sync.save('Shift', shift); // typed: a wrong field or type doesn't compile
+
+await db.deleteVenue(id);
+sync.delete('Venue', id);
+```
+
+First time sync is turned on for existing data: `sync.importAll('Shift', allShifts)`.
+
+## Status
+
+```tsx
+const { supported, account, syncing, initialSyncDone, pendingUploads, pendingChanges, lastSyncedAt, error } = useCloudSync(sync);
+```
+
+`sync.syncNow()` syncs right away (e.g. pull to refresh). It also syncs when the app comes back to the front, and when another device pushes a change.
+
+## Conflicts
+
+- `'newest'` (default): the later edit wins. A delete from another device wins over a local edit.
+- `'server'`: iCloud's version wins.
+- `'device'`: this device's version wins, also over a delete.
+
+Fields your app doesn't know (e.g. added by a newer app version on another device) are never removed from iCloud.
+
+## Release checklist
+
+- In the [CloudKit Console](https://icloud.developer.apple.com), deploy the schema to production before the App Store release. In development, record types and fields are created automatically on first save.
+- Reserved field names: `id`, `ekModifiedAt`, anything starting with `ek_`, and CloudKit's own (`recordName`, `createdAt`, …).
+
+## What's tested
+
+Tested on a real iPhone (iOS 27, Xcode 27, Expo SDK 57):
+
+- Upload, and download on a fresh install (103 records + links between them)
+- Records arriving in any order (a note before its folder)
+- Files: upload and download, file type kept
+
+Tested with automated tests only:
+
+- Waiting changes survive an app kill (the module's SQLite store)
+- Value checks and conversions for every field kind
+- Typed API: wrong records don't compile
+
+Built but not tested yet:
+
+- Two devices editing the same record (conflict rules `newest`, `server`, `device`)
+- Push: a change on one device showing up on another without opening the app
+- Signing out of iCloud, switching accounts, deleting the app's iCloud data
+
+## License
+
+MIT

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require('./plugin/build');

package/build/codec.d.ts

@@ -0,0 +1,6 @@
+import type { CloudSchema } from './schema';
+/** App record → plain fields for the native side (dates as milliseconds, no `id`, no `undefined`). */
+export declare function encodeFields(schema: CloudSchema, type: string, record: Record<string, unknown>): Record<string, unknown>;
+/** Native fields → app record (milliseconds back to `Date`, empty optionals as `null`). */
+export declare function decodeRecord(schema: CloudSchema, type: string, id: string, fields: Record<string, unknown>): Record<string, unknown> | null;
+//# sourceMappingURL=codec.d.ts.map

package/build/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASxH;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAC1B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAehC"}

package/build/codec.js

@@ -0,0 +1,34 @@
+/** App record → plain fields for the native side (dates as milliseconds, no `id`, no `undefined`). */
+export function encodeFields(schema, type, record) {
+    const fields = schema.types[type];
+    if (!fields)
+        throw new Error(`"${type}" isn't a record type in the schema.`);
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (key === 'id' || value === undefined)
+            continue;
+        result[key] = value instanceof Date ? value.getTime() : value;
+    }
+    return result;
+}
+/** Native fields → app record (milliseconds back to `Date`, empty optionals as `null`). */
+export function decodeRecord(schema, type, id, fields) {
+    const spec = schema.types[type];
+    if (!spec)
+        return null;
+    const record = { id };
+    for (const [name, field] of Object.entries(spec)) {
+        const value = fields[name];
+        if (value === undefined || value === null) {
+            record[name] = null;
+        }
+        else if (field.kind === 'date' && typeof value === 'number') {
+            record[name] = new Date(value);
+        }
+        else {
+            record[name] = value;
+        }
+    }
+    return record;
+}
+//# sourceMappingURL=codec.js.map

package/build/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAEA,sGAAsG;AACtG,MAAM,UAAU,YAAY,CAAC,MAAmB,EAAE,IAAY,EAAE,MAA+B;IAC7F,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,sCAAsC,CAAC,CAAC;IAC7E,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAChE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,YAAY,CAC1B,MAAmB,EACnB,IAAY,EACZ,EAAU,EACV,MAA+B;IAE/B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,MAAM,GAA4B,EAAE,EAAE,EAAE,CAAC;IAC/C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAC1C,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACtB,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9D,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACvB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/build/index.d.ts

@@ -0,0 +1,7 @@
+export { defineCloudSchema, field, type CloudRecord, type CloudSchema, type Field, type FieldKind, type RecordTypeName, } from './schema';
+export { createCloudSync, type ApplyHandlers, type CloudSync, type CloudSyncOptions, type CloudSyncStatus, type ConflictRule, } from './sync';
+export { useCloudSync } from './use-cloud-sync';
+export type { AccountChangeKind, AccountStatus } from './native';
+/** `true` when the native module is linked (a development or release build on iOS). */
+export declare function isCloudKitSupported(): boolean;
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,iBAAiB,EACjB,KAAK,EACL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,cAAc,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEjE,uFAAuF;AACvF,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C"}

package/build/index.js

@@ -0,0 +1,9 @@
+import { nativeModule } from './native';
+export { defineCloudSchema, field, } from './schema';
+export { createCloudSync, } from './sync';
+export { useCloudSync } from './use-cloud-sync';
+/** `true` when the native module is linked (a development or release build on iOS). */
+export function isCloudKitSupported() {
+    return nativeModule?.isSupported() ?? false;
+}
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,EACL,iBAAiB,EACjB,KAAK,GAMN,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,eAAe,GAMhB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhD,uFAAuF;AACvF,MAAM,UAAU,mBAAmB;IACjC,OAAO,YAAY,EAAE,WAAW,EAAE,IAAI,KAAK,CAAC;AAC9C,CAAC"}

package/build/native.d.ts

@@ -0,0 +1,86 @@
+import { SharedObject, type NativeModule } from 'expo';
+import type { SchemaSpec } from './schema';
+export type AccountStatus = 'available' | 'noAccount' | 'restricted' | 'temporarilyUnavailable' | 'couldNotDetermine' | 'unknown';
+export type NativeStatus = {
+    account: AccountStatus;
+    syncing: boolean;
+    initialSyncDone: boolean;
+    pendingUploads: number;
+    pendingChanges: number;
+    /** Milliseconds since 1970. */
+    lastSyncedAt: number | null;
+    error: string | null;
+};
+export type NativeChange = {
+    sequence: number;
+    type: string;
+    id: string;
+    operation: 'save' | 'delete';
+    fields: Record<string, unknown>;
+};
+export type AccountChangeKind = 'signIn' | 'signOut' | 'switchAccounts' | 'cloudDataDeleted' | 'unknown';
+export type NativeEvents = {
+    status: (status: NativeStatus) => void;
+    changes: () => void;
+    account: (change: {
+        change: AccountChangeKind;
+        account: AccountStatus;
+    }) => void;
+    error: (error: {
+        message: string;
+        context: string;
+    }) => void;
+};
+export type EngineOptions = {
+    containerId: string;
+    zoneName: string;
+    conflict: 'newest' | 'server' | 'device';
+    schema: SchemaSpec;
+};
+/** The native engine. Everything that touches iCloud runs in Swift. */
+export interface NativeEngine {
+    start(): Promise<void>;
+    syncNow(): Promise<void>;
+    stop(): Promise<void>;
+    save(input: {
+        type: string;
+        id: string;
+        fields: Record<string, unknown>;
+    }): void;
+    delete(input: {
+        type: string;
+        id: string;
+    }): void;
+    pendingChanges(limit: number): Promise<NativeChange[]>;
+    ack(sequences: number[]): Promise<void>;
+    status(): NativeStatus;
+    addListener<E extends keyof NativeEvents>(event: E, listener: NativeEvents[E]): {
+        remove(): void;
+    };
+}
+declare class CloudSyncEngine extends SharedObject<NativeEvents> implements NativeEngine {
+    constructor(options: EngineOptions);
+    start(): Promise<void>;
+    syncNow(): Promise<void>;
+    stop(): Promise<void>;
+    save(input: {
+        type: string;
+        id: string;
+        fields: Record<string, unknown>;
+    }): void;
+    delete(input: {
+        type: string;
+        id: string;
+    }): void;
+    pendingChanges(limit: number): Promise<NativeChange[]>;
+    ack(sequences: number[]): Promise<void>;
+    status(): NativeStatus;
+}
+declare class ExpoKitCloudKitModule extends NativeModule {
+    isSupported(): boolean;
+    CloudSyncEngine: typeof CloudSyncEngine;
+}
+export declare const nativeModule: ExpoKitCloudKitModule | null;
+export declare function createNativeEngine(options: EngineOptions): NativeEngine | null;
+export {};
+//# sourceMappingURL=native.d.ts.map

package/build/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"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"}

package/build/native.js

@@ -0,0 +1,7 @@
+import { requireOptionalNativeModule } from 'expo';
+// Null in Expo Go, on Android and on web, where the native module isn't linked.
+export const nativeModule = requireOptionalNativeModule('ExpoKitCloudKit');
+export function createNativeEngine(options) {
+    return nativeModule ? new nativeModule.CloudSyncEngine(options) : null;
+}
+//# sourceMappingURL=native.js.map

package/build/native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.js","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAmC,MAAM,MAAM,CAAC;AA6EpF,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,2BAA2B,CAAwB,iBAAiB,CAAC,CAAC;AAElG,MAAM,UAAU,kBAAkB,CAAC,OAAsB;IACvD,OAAO,YAAY,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACzE,CAAC"}

package/build/schema.d.ts

@@ -0,0 +1,98 @@
+export type FieldKind = 'string' | 'int' | 'double' | 'bool' | 'date' | 'stringList' | 'intList' | 'doubleList' | 'reference' | 'asset';
+type ValueOfKind = {
+    string: string;
+    int: number;
+    double: number;
+    bool: boolean;
+    date: Date;
+    stringList: string[];
+    intList: number[];
+    doubleList: number[];
+    /** The ID of the linked record. */
+    reference: string;
+    /** A local file path (`file://…` or an absolute path). */
+    asset: string;
+};
+export type Field<K extends FieldKind = FieldKind, Optional extends boolean = boolean, Target extends string = string> = {
+    readonly kind: K;
+    readonly isOptional: Optional;
+    /** For references: the record type it links to. */
+    readonly target: K extends 'reference' ? Target : undefined;
+};
+/** A field that can also be left out or set to `null`. */
+type Optionalizable<K extends FieldKind, Target extends string = string> = Field<K, false, Target> & {
+    optional(): Field<K, true, Target>;
+};
+/** Field kinds for `defineCloudSchema`. Add `.optional()` for a field that can be empty. */
+export declare const field: {
+    string: () => Optionalizable<"string", string>;
+    /** Whole numbers. Stored as a 64-bit integer. */
+    int: () => Optionalizable<"int", string>;
+    double: () => Optionalizable<"double", string>;
+    bool: () => Optionalizable<"bool", string>;
+    date: () => Optionalizable<"date", string>;
+    stringList: () => Optionalizable<"stringList", string>;
+    intList: () => Optionalizable<"intList", string>;
+    doubleList: () => Optionalizable<"doubleList", string>;
+    /** A link to another record type in the same schema, by its ID. */
+    reference: <Target extends string>(target: Target) => Optionalizable<"reference", Target>;
+    /** A file stored in iCloud. The app passes and gets back a local file path. */
+    asset: () => Optionalizable<"asset", string>;
+};
+type AnyField = Field<FieldKind, boolean, string>;
+type FieldsShape = Record<string, AnyField>;
+export type SchemaShape = Record<string, FieldsShape>;
+/** Every reference must point to a record type in the same schema. */
+type CheckReferences<S extends SchemaShape> = {
+    [T in keyof S]: {
+        [F in keyof S[T]]: S[T][F] extends Field<'reference', boolean, infer Target> ? Target extends keyof S ? S[T][F] : Field<'reference', boolean, Extract<keyof S, string>> : S[T][F];
+    };
+};
+export type CloudSchema<S extends SchemaShape = SchemaShape> = {
+    readonly types: S;
+};
+/** The names of the record types in a schema, e.g. `'Shift' | 'Venue'`. */
+export type RecordTypeName<S extends CloudSchema> = Extract<keyof S['types'], string>;
+type FieldValue<F> = F extends Field<infer K, boolean, string> ? ValueOfKind[K] : never;
+type RequiredKeys<Fs> = {
+    [K in keyof Fs]: Fs[K] extends Field<FieldKind, false, string> ? K : never;
+}[keyof Fs];
+type OptionalKeys<Fs> = {
+    [K in keyof Fs]: Fs[K] extends Field<FieldKind, false, string> ? never : K;
+}[keyof Fs];
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * The TypeScript type of one record, e.g. `CloudRecord<typeof schema, 'Shift'>`.
+ * Every record has a string `id`. Optional fields can be left out or `null`.
+ */
+export type CloudRecord<S extends CloudSchema, T extends RecordTypeName<S>> = Simplify<{
+    id: string;
+} & {
+    [K in RequiredKeys<S['types'][T]>]: FieldValue<S['types'][T][K]>;
+} & {
+    [K in OptionalKeys<S['types'][T]>]?: FieldValue<S['types'][T][K]> | null;
+}>;
+/**
+ * Describes the app's data for iCloud. One entry per record type, one field kind per field.
+ * Throws when a name isn't allowed in CloudKit or a reference points to an unknown type.
+ *
+ * Rule after release: only add fields and types. Never rename or remove one.
+ */
+export declare function defineCloudSchema<const S extends SchemaShape>(types: S & CheckReferences<S>): CloudSchema<S>;
+export type SchemaSpec = {
+    types: {
+        name: string;
+        fields: {
+            name: string;
+            kind: FieldKind;
+            optional: boolean;
+            target: string | null;
+        }[];
+    }[];
+};
+/** The plain description sent to the native side. */
+export declare function toSchemaSpec(schema: CloudSchema): SchemaSpec;
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/build/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/build/schema.js

@@ -0,0 +1,83 @@
+function make(kind, target) {
+    const base = { kind, isOptional: false, target: (target ?? undefined) };
+    return { ...base, optional: () => ({ ...base, isOptional: true }) };
+}
+/** Field kinds for `defineCloudSchema`. Add `.optional()` for a field that can be empty. */
+export const field = {
+    string: () => make('string'),
+    /** Whole numbers. Stored as a 64-bit integer. */
+    int: () => make('int'),
+    double: () => make('double'),
+    bool: () => make('bool'),
+    date: () => make('date'),
+    stringList: () => make('stringList'),
+    intList: () => make('intList'),
+    doubleList: () => make('doubleList'),
+    /** A link to another record type in the same schema, by its ID. */
+    reference: (target) => make('reference', target),
+    /** A file stored in iCloud. The app passes and gets back a local file path. */
+    asset: () => make('asset'),
+};
+/** Names CloudKit or this package use for themselves. */
+const RESERVED_FIELD_NAMES = new Set([
+    'id',
+    'recordName',
+    'recordID',
+    'recordType',
+    'createdAt',
+    'modifiedAt',
+    'createdBy',
+    'modifiedBy',
+    'creationDate',
+    'modificationDate',
+    'creatorUserRecordID',
+    'lastModifiedUserRecordID',
+    'recordChangeTag',
+    'ekModifiedAt',
+]);
+// CloudKit: starts with a letter, then letters, digits or underscores, at most 255 characters.
+const NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,254}$/;
+/**
+ * Describes the app's data for iCloud. One entry per record type, one field kind per field.
+ * Throws when a name isn't allowed in CloudKit or a reference points to an unknown type.
+ *
+ * Rule after release: only add fields and types. Never rename or remove one.
+ */
+export function defineCloudSchema(types) {
+    const typeNames = Object.keys(types);
+    if (typeNames.length === 0)
+        throw new Error('defineCloudSchema: add at least one record type.');
+    for (const typeName of typeNames) {
+        if (!NAME_PATTERN.test(typeName)) {
+            throw new Error(`defineCloudSchema: "${typeName}" isn't a valid record type name (letters, digits, _; starts with a letter).`);
+        }
+        const fields = types[typeName];
+        for (const [fieldName, spec] of Object.entries(fields)) {
+            if (!NAME_PATTERN.test(fieldName)) {
+                throw new Error(`defineCloudSchema: ${typeName}.${fieldName} isn't a valid field name (letters, digits, _; starts with a letter).`);
+            }
+            if (RESERVED_FIELD_NAMES.has(fieldName) || fieldName.startsWith('ek_')) {
+                throw new Error(`defineCloudSchema: ${typeName}.${fieldName} is a reserved name. Pick another one.`);
+            }
+            if (spec.kind === 'reference' && !typeNames.includes(spec.target)) {
+                throw new Error(`defineCloudSchema: ${typeName}.${fieldName} links to "${String(spec.target)}", which isn't in the schema.`);
+            }
+        }
+    }
+    return { types: types };
+}
+/** The plain description sent to the native side. */
+export function toSchemaSpec(schema) {
+    return {
+        types: Object.entries(schema.types).map(([name, fields]) => ({
+            name,
+            fields: Object.entries(fields).map(([fieldName, spec]) => ({
+                name: fieldName,
+                kind: spec.kind,
+                optional: spec.isOptional,
+                target: spec.kind === 'reference' ? spec.target : null,
+            })),
+        })),
+    };
+}
+//# sourceMappingURL=schema.js.map

package/build/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/build/sync.d.ts

@@ -0,0 +1,78 @@
+import { createNativeEngine, type AccountChangeKind, type AccountStatus } from './native';
+import { type CloudRecord, type CloudSchema, type RecordTypeName } from './schema';
+export type ConflictRule = 'newest' | 'server' | 'device';
+type MaybePromise = void | Promise<void>;
+/** How the app writes changes from iCloud into its own database, per record type. */
+export type ApplyHandlers<S extends CloudSchema> = {
+    [T in RecordTypeName<S>]: {
+        /** New or changed records from another device. Insert or update them. */
+        save: (records: CloudRecord<S, T>[]) => MaybePromise;
+        /** Records deleted on another device. */
+        delete: (ids: string[]) => MaybePromise;
+    };
+};
+export type CloudSyncOptions<S extends CloudSchema> = {
+    /** iCloud container ID, also listed in the config plugin, e.g. `'iCloud.com.example.app'`. */
+    container: string;
+    schema: S;
+    apply: ApplyHandlers<S>;
+    /**
+     * Who wins when the same record changed on two devices. Default `'newest'`: the later edit wins,
+     * and a delete from another device wins over a local edit. `'server'`: iCloud wins. `'device'`: this device wins.
+     */
+    conflict?: ConflictRule;
+    /** Default `'AppData'`. Only change it to run two separate syncs in one app. */
+    zone?: string;
+    /**
+     * Called when the iCloud account changes (signed out, switched accounts) or this app's iCloud
+     * data was deleted. Sync state is reset; the app decides what to do with its local data,
+     * e.g. keep it and call `importAll` to upload it to the new account.
+     */
+    onAccountChange?: (event: {
+        change: AccountChangeKind;
+        account: AccountStatus;
+    }) => void;
+    /** Sync when the app comes back to the front. Default `true`. */
+    syncOnForeground?: boolean;
+};
+export type CloudSyncStatus = {
+    /** `false` in Expo Go, on Android and on web. Everything else is then a no-op. */
+    supported: boolean;
+    account: AccountStatus;
+    syncing: boolean;
+    /** The first download finished. Local changes upload only after that. */
+    initialSyncDone: boolean;
+    /** Local changes not yet in iCloud. */
+    pendingUploads: number;
+    /** Changes from iCloud not yet applied to the app's database. */
+    pendingChanges: number;
+    lastSyncedAt: Date | null;
+    /** The last error, if the last sync didn't finish. */
+    error: string | null;
+};
+export type CloudSync<S extends CloudSchema> = {
+    /** Starts syncing: downloads first, then uploads. Call once, e.g. after the app's database is ready. */
+    start(): Promise<void>;
+    /** Queues a new or changed record for upload. Call after every local insert or update. */
+    save<T extends RecordTypeName<S>>(type: T, record: CloudRecord<S, T>): void;
+    /** Queues a delete. Call after every local delete. */
+    delete<T extends RecordTypeName<S>>(type: T, id: string): void;
+    /** Queues many records at once, e.g. existing data the first time sync is turned on. */
+    importAll<T extends RecordTypeName<S>>(type: T, records: CloudRecord<S, T>[]): void;
+    /** Downloads and uploads now, e.g. pull to refresh. */
+    syncNow(): Promise<void>;
+    getStatus(): CloudSyncStatus;
+    /** Calls `listener` on every status change. Returns a function that stops it. */
+    subscribe(listener: (status: CloudSyncStatus) => void): () => void;
+    /** Stops syncing and releases the native engine. */
+    stop(): Promise<void>;
+};
+/**
+ * Creates the sync for one schema. Create it once (module level) and call `start()`.
+ * In Expo Go (no native module) every method is a safe no-op.
+ */
+export declare function createCloudSync<S extends CloudSchema>(options: CloudSyncOptions<S>): CloudSync<S>;
+/** Internal: lets tests pass a fake engine. */
+export declare function createCloudSyncWithEngine<S extends CloudSchema>(options: CloudSyncOptions<S>, makeEngine: typeof createNativeEngine): CloudSync<S>;
+export {};
+//# sourceMappingURL=sync.d.ts.map

package/build/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"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"}