@expo-kit/cloudkit 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@expo-kit/cloudkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Typed CloudKit sync for Expo apps, built on CKSyncEngine",
+  "keywords": [
+    "expo",
+    "expo-kit",
+    "react-native",
+    "cloudkit",
+    "icloud",
+    "sync"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/islamashraful/expo-kit.git",
+    "directory": "packages/cloudkit"
+  },
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "react-native": "./src/index.ts",
+      "default": "./build/index.js"
+    },
+    "./app.plugin.js": "./app.plugin.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "build",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "ios",
+    "plugin/build",
+    "app.plugin.js",
+    "expo-module.config.json"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p plugin/tsconfig.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p plugin/tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@expo-kit/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.0",
+    "@types/react": "~19.2.2",
+    "expo": "~57.0.28",
+    "typescript": "~6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin/build/index.d.ts

@@ -0,0 +1,7 @@
+import { type ConfigPlugin } from 'expo/config-plugins';
+export type CloudKitPluginOptions = {
+    /** iCloud container IDs the app uses, e.g. `['iCloud.com.example.app']`. */
+    containers: string[];
+};
+declare const _default: ConfigPlugin<CloudKitPluginOptions>;
+export default _default;

package/plugin/build/index.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_plugins_1 = require("expo/config-plugins");
+// CKSyncEngine needs iOS 17.
+const MIN_IOS = '17.0';
+const withCloudKit = (config, options) => {
+    const containers = options?.containers ?? [];
+    if (containers.length === 0) {
+        throw new Error('@expo-kit/cloudkit: pass at least one iCloud container, e.g. { containers: ["iCloud.com.example.app"] }');
+    }
+    config = (0, config_plugins_1.withEntitlementsPlist)(config, (mod) => {
+        const entitlements = mod.modResults;
+        entitlements['com.apple.developer.icloud-container-identifiers'] = unique([
+            ...asStrings(entitlements['com.apple.developer.icloud-container-identifiers']),
+            ...containers,
+        ]);
+        entitlements['com.apple.developer.icloud-services'] = unique([
+            ...asStrings(entitlements['com.apple.developer.icloud-services']),
+            'CloudKit',
+        ]);
+        // Silent pushes tell the app that something changed in iCloud.
+        entitlements['aps-environment'] ??= 'development';
+        return mod;
+    });
+    config = (0, config_plugins_1.withInfoPlist)(config, (mod) => {
+        mod.modResults.UIBackgroundModes = unique([...asStrings(mod.modResults.UIBackgroundModes), 'remote-notification']);
+        // Read by the module to refuse unknown containers with a clear error. CloudKit itself
+        // crashes the app when a container is missing from the entitlements.
+        mod.modResults.ExpoKitCloudKitContainers = containers;
+        return mod;
+    });
+    config = (0, config_plugins_1.withPodfileProperties)(config, (mod) => {
+        const current = mod.modResults['ios.deploymentTarget'];
+        if (!current || compareVersions(current, MIN_IOS) < 0)
+            mod.modResults['ios.deploymentTarget'] = MIN_IOS;
+        return mod;
+    });
+    // The app target must be at least 17.0 too, or it can't link the module.
+    config = (0, config_plugins_1.withXcodeProject)(config, (mod) => {
+        const configurations = mod.modResults.pbxXCBuildConfigurationSection();
+        for (const configuration of Object.values(configurations)) {
+            const settings = typeof configuration === 'object' ? configuration.buildSettings : undefined;
+            const current = settings?.IPHONEOS_DEPLOYMENT_TARGET;
+            if (settings && current && compareVersions(current.replace(/"/g, ''), MIN_IOS) < 0) {
+                settings.IPHONEOS_DEPLOYMENT_TARGET = MIN_IOS;
+            }
+        }
+        return mod;
+    });
+    return config;
+};
+function asStrings(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function compareVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+exports.default = (0, config_plugins_1.createRunOncePlugin)(withCloudKit, '@expo-kit/cloudkit');

package/src/codec.ts

@@ -0,0 +1,36 @@
+import type { CloudSchema } from './schema';
+
+/** App record → plain fields for the native side (dates as milliseconds, no `id`, no `undefined`). */
+export function encodeFields(schema: CloudSchema, type: string, record: Record<string, unknown>): Record<string, unknown> {
+  const fields = schema.types[type];
+  if (!fields) throw new Error(`"${type}" isn't a record type in the schema.`);
+  const result: Record<string, unknown> = {};
+  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: CloudSchema,
+  type: string,
+  id: string,
+  fields: Record<string, unknown>,
+): Record<string, unknown> | null {
+  const spec = schema.types[type];
+  if (!spec) return null;
+  const record: Record<string, unknown> = { 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;
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+import { nativeModule } from './native';
+
+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 function isCloudKitSupported(): boolean {
+  return nativeModule?.isSupported() ?? false;
+}

package/src/native.ts

@@ -0,0 +1,83 @@
+import { requireOptionalNativeModule, 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;
+}
+
+// Null in Expo Go, on Android and on web, where the native module isn't linked.
+export const nativeModule = requireOptionalNativeModule<ExpoKitCloudKitModule>('ExpoKitCloudKit');
+
+export function createNativeEngine(options: EngineOptions): NativeEngine | null {
+  return nativeModule ? new nativeModule.CloudSyncEngine(options) : null;
+}

package/src/schema.ts

@@ -0,0 +1,169 @@
+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>;
+};
+
+function make<K extends FieldKind, Target extends string = string>(
+  kind: K,
+  target?: Target,
+): Optionalizable<K, Target> {
+  const base = { kind, isOptional: false as const, target: (target ?? undefined) as never };
+  return { ...base, optional: () => ({ ...base, isOptional: true as const }) } as unknown as Optionalizable<K, Target>;
+}
+
+/** 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 extends string>(target: Target) => make('reference', target),
+  /** A file stored in iCloud. The app passes and gets back a local file path. */
+  asset: () => make('asset'),
+};
+
+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;
+  }
+>;
+
+/** 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<const S extends SchemaShape>(types: S & CheckReferences<S>): CloudSchema<S> {
+  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] as FieldsShape;
+    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 as string)) {
+        throw new Error(`defineCloudSchema: ${typeName}.${fieldName} links to "${String(spec.target)}", which isn't in the schema.`);
+      }
+    }
+  }
+  return { types: types as 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 function toSchemaSpec(schema: CloudSchema): SchemaSpec {
+  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 as string) : null,
+      })),
+    })),
+  };
+}