@trainstar/synchro-react-native 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Trainstar
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# `@trainstar/synchro-react-native`
+
+React Native TurboModule bridge for Synchro. The package wraps the native Swift and Kotlin SDKs; it does not implement a separate sync engine in JavaScript.
+
+## Requirements
+
+- React Native `0.83.x`
+- iOS `16.0+`
+- Android `minSdk 24`
+- Node `20+`
+- Android development and CI should use JDK `17`
+
+## Installation
+
+```sh
+npm install @trainstar/synchro-react-native
+```
+
+iOS:
+
+```sh
+cd ios
+pod install
+```
+
+Android autolinks through the React Native Gradle plugin. No manual `MainApplication` edits are required.
+
+## Usage
+
+```ts
+import { SynchroClient } from '@trainstar/synchro-react-native';
+
+const client = new SynchroClient({
+  dbPath: 'synchro.db',
+  serverURL: 'https://api.example.com',
+  authProvider: async () => '<jwt>',
+  clientID: 'device-1',
+  appVersion: '1.0.0',
+});
+
+await client.initialize();
+await client.start();
+
+const rows = await client.query('SELECT * FROM tasks WHERE done = ?', [0]);
+await client.execute('UPDATE tasks SET done = ? WHERE id = ?', [1, rows[0].id]);
+```
+
+## Public API
+
+Core methods:
+
+- `initialize()`
+- `query(sql, params?)`
+- `queryOne(sql, params?)`
+- `execute(sql, params?)`
+- `executeBatch(statements)`
+- `createTable(...)`
+- `alterTable(...)`
+- `createIndex(...)`
+- `pendingChangeCount()`
+- `start()`
+- `stop()`
+- `syncNow()`
+- `close()`
+
+Events and hooks:
+
+- `onStatusChange(callback)`
+- `onConflict(callback)`
+- `onSnapshotRequired(handler)`
+- `useQuery(client, sql, params?, tables?)`
+- `useSyncStatus(client)`
+- `usePendingChanges(client, pollInterval?)`
+
+## Transactions
+
+`writeTransaction()` and `readTransaction()` mirror the native SDKs through a bridge-held transaction session.
+
+Contract:
+
+- The callback must only perform database work.
+- Do not perform network I/O or long-running waits inside the callback.
+- Transactions time out after 5 seconds of inactivity and reject with `TransactionTimeoutError`.
+
+```ts
+await client.writeTransaction(async (tx) => {
+  await tx.execute(
+    'INSERT INTO tasks (id, title, done) VALUES (?, ?, ?)',
+    ['task-1', 'Ship RN SDK', 0]
+  );
+});
+```
+
+## Errors
+
+Native errors are normalized to typed JS errors, including:
+
+- `NotConnectedError`
+- `SchemaNotLoadedError`
+- `TableNotSyncedError`
+- `UpgradeRequiredError`
+- `SchemaMismatchError`
+- `SnapshotRequiredError`
+- `PushRejectedError`
+- `NetworkError`
+- `ServerError`
+- `DatabaseError`
+- `InvalidResponseError`
+- `AlreadyStartedError`
+- `NotStartedError`
+- `TransactionTimeoutError`
+
+## Development
+
+```sh
+npm run typecheck
+npm run test:unit
+npm run prepare
+npm run pack:dry-run
+```
+
+The example app in [`example/`](./example) is the end-to-end harness used for RN bridge verification on iOS and Android.

package/SynchroReactNative.podspec

@@ -0,0 +1,22 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "SynchroReactNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => "16.0" }
+  s.source       = { :git => "https://github.com/trainstar/synchro.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  s.dependency "Synchro", "~> 0.1"
+
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,81 @@
+buildscript {
+  ext.SynchroReactNative = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return SynchroReactNative[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+    mavenLocal()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.trainstar.synchro.rn"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+  }
+
+  sourceSets {
+    main {
+      kotlin.srcDirs = ['src/main/kotlin']
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+repositories {
+  mavenLocal()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "com.trainstar:synchro:0.1.0"
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0"
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.trainstar.synchro.rn">
+</manifest>