local-lite 0.2.1 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -2
- package/bin/local-lite.mjs +65 -61
- package/dist/auth/local.d.ts +33 -1
- package/dist/auth/local.js +94 -13
- package/package.json +1 -2
- package/skills/local-lite-auth/SKILL.md +67 -27
- package/skills/local-lite-server/SKILL.md +127 -0
- package/docs/.nojekyll +0 -1
- package/docs/README.md +0 -108
- package/docs/_sidebar.md +0 -22
- package/docs/actions-email.md +0 -222
- package/docs/adapters-local.md +0 -272
- package/docs/adapters-remote.md +0 -291
- package/docs/api-keys.md +0 -114
- package/docs/architecture.md +0 -106
- package/docs/auth.md +0 -342
- package/docs/backups.md +0 -214
- package/docs/breaking-changes.md +0 -147
- package/docs/client-api.md +0 -412
- package/docs/configuration.md +0 -228
- package/docs/conflict-resolution.md +0 -78
- package/docs/getting-started.md +0 -190
- package/docs/google-auth.md +0 -234
- package/docs/index.html +0 -166
- package/docs/kv.md +0 -89
- package/docs/maintenance-portability.md +0 -133
- package/docs/react-hooks.md +0 -457
- package/docs/scheduler.md +0 -81
- package/docs/search.md +0 -71
- package/docs/server.md +0 -101
- package/docs/session.md +0 -129
- package/docs/storage.md +0 -265
|
@@ -1,78 +0,0 @@
|
|
|
1
|
-
# 🛡️ Conflict Resolution
|
|
2
|
-
|
|
3
|
-
When multiple offline clients modify the same record concurrently, `local-lite` resolves conflicts during the pull phase.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## 1. Built-in Strategies
|
|
8
|
-
|
|
9
|
-
Specify your strategy directly in `defineSyncConfig`:
|
|
10
|
-
|
|
11
|
-
```typescript
|
|
12
|
-
export const config = defineSyncConfig({
|
|
13
|
-
conflictResolver: 'field-merge', // Options: 'last-write-wins' | 'server-wins' | 'client-wins' | 'field-merge'
|
|
14
|
-
});
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
### Strategy Summary:
|
|
18
|
-
|
|
19
|
-
| Strategy | Description | Best For |
|
|
20
|
-
| :--- | :--- | :--- |
|
|
21
|
-
| **`field-merge`** (Recommended) | 3-Way field-level merge. Merges disjoint fields from both local and remote offline edits, and uses timestamps or custom rules for conflicting fields. | Collaborative apps where multiple users edit different properties of the same item. |
|
|
22
|
-
| **`last-write-wins`** (Default) | Compares mutation timestamps. The mutation with the most recent timestamp wins the entire record. | Standard apps where record replacement is acceptable. |
|
|
23
|
-
| **`server-wins`** | Any incoming remote record overrides uncommitted local edits. | Authoritative server data (banking, ticket inventory). |
|
|
24
|
-
| **`client-wins`** | Local changes always override incoming remote changes. | Personal draft tools, private preferences. |
|
|
25
|
-
|
|
26
|
-
---
|
|
27
|
-
|
|
28
|
-
## 2. Smart 3-Way Field-Level Conflict Resolver (`createFieldMergeResolver`)
|
|
29
|
-
|
|
30
|
-
Instead of picking all-local or all-remote, `createFieldMergeResolver` intelligently inspects individual columns:
|
|
31
|
-
* **Disjoint edits preserved:** If user A modifies `title` offline and user B modifies `notes` on the server, both changes are preserved in the merged row.
|
|
32
|
-
* **Granular field rules:** Apply `max`, `min`, `newer`, `local`, `remote`, or custom functions per table and column.
|
|
33
|
-
* **Custom delete handling:** Choose whether deletions win (`delete-wins`) or offline edits take precedence (`update-wins`).
|
|
34
|
-
|
|
35
|
-
```typescript
|
|
36
|
-
import { createFieldMergeResolver } from 'local-lite';
|
|
37
|
-
import { defineSyncConfig } from 'local-lite/config';
|
|
38
|
-
|
|
39
|
-
export const config = defineSyncConfig({
|
|
40
|
-
conflictResolver: createFieldMergeResolver({
|
|
41
|
-
defaultWinner: 'newer', // Default for overlapping fields without explicit rules
|
|
42
|
-
deleteHandling: 'delete-wins',
|
|
43
|
-
fieldRules: {
|
|
44
|
-
notes: {
|
|
45
|
-
// Automatically union tag arrays
|
|
46
|
-
tags: (localTags, remoteTags) =>
|
|
47
|
-
Array.from(new Set([...(localTags ?? []), ...(remoteTags ?? [])])),
|
|
48
|
-
// Highest counter wins
|
|
49
|
-
view_count: 'max',
|
|
50
|
-
},
|
|
51
|
-
'*': {
|
|
52
|
-
updated_at: 'newer',
|
|
53
|
-
},
|
|
54
|
-
},
|
|
55
|
-
}),
|
|
56
|
-
});
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
---
|
|
60
|
-
|
|
61
|
-
## 3. Low-Level Custom Conflict Resolvers
|
|
62
|
-
|
|
63
|
-
You can also provide a completely custom resolver function:
|
|
64
|
-
|
|
65
|
-
```typescript
|
|
66
|
-
import { defineSyncConfig } from 'local-lite/config';
|
|
67
|
-
import { ConflictContext } from 'local-lite';
|
|
68
|
-
|
|
69
|
-
export const config = defineSyncConfig({
|
|
70
|
-
conflictResolver: (context: ConflictContext) => {
|
|
71
|
-
const { localOutboxRecord, remoteChange, localRow } = context;
|
|
72
|
-
|
|
73
|
-
// Return 'apply-remote' | 'keep-local' | { mergePayload: Record<string, any> }
|
|
74
|
-
return 'apply-remote';
|
|
75
|
-
},
|
|
76
|
-
});
|
|
77
|
-
```
|
|
78
|
-
|
package/docs/getting-started.md
DELETED
|
@@ -1,190 +0,0 @@
|
|
|
1
|
-
# 🚀 Getting Started with local-lite
|
|
2
|
-
|
|
3
|
-
This guide walks you through installing `local-lite` and setting up your first offline-first sync pipeline in 5 minutes.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## 1. Installation
|
|
8
|
-
|
|
9
|
-
Install the core package:
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
npm install local-lite
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
### Install Drivers & Backend Dependencies
|
|
16
|
-
|
|
17
|
-
Install the SQLite driver for your target platform and your chosen cloud backend:
|
|
18
|
-
|
|
19
|
-
#### For Expo (iOS, Android, Web)
|
|
20
|
-
```bash
|
|
21
|
-
npx expo install expo-sqlite @react-native-community/netinfo
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
#### For Bare React Native
|
|
25
|
-
```bash
|
|
26
|
-
npm install @op-engineering/op-sqlite @react-native-community/netinfo
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
#### For Node.js / Electron / Desktop
|
|
30
|
-
```bash
|
|
31
|
-
npm install better-sqlite3
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
#### Cloud Backends (choose one)
|
|
35
|
-
```bash
|
|
36
|
-
# If using Supabase
|
|
37
|
-
npm install @supabase/supabase-js
|
|
38
|
-
|
|
39
|
-
# If using Convex
|
|
40
|
-
npm install convex
|
|
41
|
-
|
|
42
|
-
# If using Firebase / Firestore
|
|
43
|
-
npm install firebase # or @react-native-firebase/firestore
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
---
|
|
47
|
-
|
|
48
|
-
## 2. Define Your Configuration
|
|
49
|
-
|
|
50
|
-
Create a file named `sync.config.ts`:
|
|
51
|
-
|
|
52
|
-
```typescript
|
|
53
|
-
// src/sync.config.ts
|
|
54
|
-
import { defineSyncConfig, createSyncClient, LocalFirstClient } from 'local-lite/config';
|
|
55
|
-
import * as SQLite from 'expo-sqlite';
|
|
56
|
-
|
|
57
|
-
export const syncConfig = defineSyncConfig({
|
|
58
|
-
// 1. Local Database instance or factory
|
|
59
|
-
database: () => SQLite.openDatabaseAsync('app.db'),
|
|
60
|
-
|
|
61
|
-
// 2. Tables to synchronize
|
|
62
|
-
tables: ['todos', 'notes'],
|
|
63
|
-
|
|
64
|
-
// 3. Create and evolve the local schema with ordered migrations
|
|
65
|
-
schemaMigrations: [
|
|
66
|
-
{
|
|
67
|
-
version: 1,
|
|
68
|
-
up: [
|
|
69
|
-
'CREATE TABLE todos (id TEXT PRIMARY KEY, title TEXT NOT NULL, completed INTEGER NOT NULL DEFAULT 0, updated_at INTEGER NOT NULL)',
|
|
70
|
-
'CREATE TABLE notes (id TEXT PRIMARY KEY, title TEXT, updated_at INTEGER NOT NULL DEFAULT 0)',
|
|
71
|
-
],
|
|
72
|
-
},
|
|
73
|
-
],
|
|
74
|
-
|
|
75
|
-
// 4. Remote backend credentials (e.g. Supabase, Convex, or in-memory demo)
|
|
76
|
-
supabase: {
|
|
77
|
-
url: process.env.EXPO_PUBLIC_SUPABASE_URL,
|
|
78
|
-
anonKey: process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY,
|
|
79
|
-
},
|
|
80
|
-
|
|
81
|
-
// 5. Conflict strategy & sync intervals
|
|
82
|
-
conflictResolver: 'last-write-wins',
|
|
83
|
-
pushIntervalMs: 3000,
|
|
84
|
-
pullIntervalMs: 8000,
|
|
85
|
-
});
|
|
86
|
-
|
|
87
|
-
// Singleton client initializer
|
|
88
|
-
let clientPromise: Promise<LocalFirstClient> | null = null;
|
|
89
|
-
export function getSyncClient(): Promise<LocalFirstClient> {
|
|
90
|
-
if (!clientPromise) {
|
|
91
|
-
clientPromise = createSyncClient(syncConfig);
|
|
92
|
-
}
|
|
93
|
-
return clientPromise;
|
|
94
|
-
}
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
---
|
|
98
|
-
|
|
99
|
-
## 3. Build a Reactive UI Component
|
|
100
|
-
|
|
101
|
-
Use `useLiveQuery` and `useSyncStatus` in your React or React Native components:
|
|
102
|
-
|
|
103
|
-
```tsx
|
|
104
|
-
// src/app/index.tsx
|
|
105
|
-
import React, { useState, useEffect } from 'react';
|
|
106
|
-
import { View, Text, TextInput, TouchableOpacity, FlatList } from 'react-native';
|
|
107
|
-
import { useLiveQuery, useSyncStatus } from 'local-lite/react';
|
|
108
|
-
import { LocalFirstClient, generateUUID } from 'local-lite';
|
|
109
|
-
import { getSyncClient } from '../sync.config';
|
|
110
|
-
|
|
111
|
-
export default function TodoApp() {
|
|
112
|
-
const [client, setClient] = useState<LocalFirstClient | null>(null);
|
|
113
|
-
const [text, setText] = useState('');
|
|
114
|
-
|
|
115
|
-
// 1. Initialize client on mount
|
|
116
|
-
useEffect(() => {
|
|
117
|
-
getSyncClient().then(setClient);
|
|
118
|
-
}, []);
|
|
119
|
-
|
|
120
|
-
// 2. Live query: automatically re-renders on local writes & remote pulls
|
|
121
|
-
const { data: todos } = useLiveQuery(client, 'todos', {
|
|
122
|
-
orderBy: 'updated_at',
|
|
123
|
-
order: 'desc',
|
|
124
|
-
});
|
|
125
|
-
|
|
126
|
-
// 3. Monitor sync engine & pending outbox queue
|
|
127
|
-
const { pendingCount, isSyncing, isOnline } = useSyncStatus(client);
|
|
128
|
-
|
|
129
|
-
// 4. Instant local write
|
|
130
|
-
const handleAddTodo = async () => {
|
|
131
|
-
if (!client || !text.trim()) return;
|
|
132
|
-
const title = text.trim();
|
|
133
|
-
setText('');
|
|
134
|
-
|
|
135
|
-
await client.insert('todos', {
|
|
136
|
-
id: generateUUID(),
|
|
137
|
-
title,
|
|
138
|
-
completed: 0,
|
|
139
|
-
updated_at: Date.now(),
|
|
140
|
-
});
|
|
141
|
-
};
|
|
142
|
-
|
|
143
|
-
const handleToggle = async (id: string, current: number) => {
|
|
144
|
-
if (!client) return;
|
|
145
|
-
await client.update('todos', id, {
|
|
146
|
-
completed: current ? 0 : 1,
|
|
147
|
-
updated_at: Date.now(),
|
|
148
|
-
});
|
|
149
|
-
};
|
|
150
|
-
|
|
151
|
-
return (
|
|
152
|
-
<View style={{ flex: 1, padding: 24 }}>
|
|
153
|
-
<Text style={{ fontSize: 20, fontWeight: 'bold' }}>Local-First Todos</Text>
|
|
154
|
-
<Text style={{ color: '#666', marginBottom: 16 }}>
|
|
155
|
-
{pendingCount > 0 ? `Syncing (${pendingCount} pending)...` : 'All changes synced'}
|
|
156
|
-
</Text>
|
|
157
|
-
|
|
158
|
-
<View style={{ flexDirection: 'row', marginBottom: 16 }}>
|
|
159
|
-
<TextInput
|
|
160
|
-
value={text}
|
|
161
|
-
onChangeText={setText}
|
|
162
|
-
placeholder="New task..."
|
|
163
|
-
style={{ flex: 1, borderWidth: 1, borderColor: '#ccc', padding: 8, borderRadius: 4 }}
|
|
164
|
-
/>
|
|
165
|
-
<TouchableOpacity onPress={handleAddTodo} style={{ backgroundColor: '#0284c7', padding: 10, marginLeft: 8, borderRadius: 4 }}>
|
|
166
|
-
<Text style={{ color: '#fff' }}>Add</Text>
|
|
167
|
-
</TouchableOpacity>
|
|
168
|
-
</View>
|
|
169
|
-
|
|
170
|
-
<FlatList
|
|
171
|
-
data={todos}
|
|
172
|
-
keyExtractor={(item) => item.id}
|
|
173
|
-
renderItem={({ item }) => (
|
|
174
|
-
<TouchableOpacity onPress={() => handleToggle(item.id, item.completed)}>
|
|
175
|
-
<Text style={{ paddingVertical: 8, textDecorationLine: item.completed ? 'line-through' : 'none' }}>
|
|
176
|
-
{item.completed ? '✅' : '⬜'} {item.title}
|
|
177
|
-
</Text>
|
|
178
|
-
</TouchableOpacity>
|
|
179
|
-
)}
|
|
180
|
-
/>
|
|
181
|
-
</View>
|
|
182
|
-
);
|
|
183
|
-
}
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
---
|
|
187
|
-
|
|
188
|
-
## Next Steps
|
|
189
|
-
- Learn how the [Transactional Outbox Architecture](./architecture.md) works under the hood.
|
|
190
|
-
- Explore driver guides in [Local Adapters](./adapters-local.md) and [Remote Adapters](./adapters-remote.md).
|
package/docs/google-auth.md
DELETED
|
@@ -1,234 +0,0 @@
|
|
|
1
|
-
# 🔑 Google Sign-In & Authentication
|
|
2
|
-
|
|
3
|
-
`local-lite` provides a zero-backend, zero-lock-in **Google OAuth 2.0 PKCE client** and React hook out of the box.
|
|
4
|
-
|
|
5
|
-
Built specifically for local-first architectures, it allows your Expo, React Native, or Web application to sign in users directly with Google without requiring a dedicated auth server, Supabase, or Firebase.
|
|
6
|
-
|
|
7
|
-
```typescript
|
|
8
|
-
import { GoogleAuthClient } from 'local-lite/auth';
|
|
9
|
-
import { useGoogleAuth } from 'local-lite/react';
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
---
|
|
13
|
-
|
|
14
|
-
## 🌟 Features
|
|
15
|
-
|
|
16
|
-
* **🛡️ PKCE Security (RFC 7636):** Automatic cryptographically secure 32-byte `code_verifier`, SHA-256 (`S256`) code challenge generation, and CSRF state validation.
|
|
17
|
-
* **👤 User Profile Fetching:** Retrieves verified user profile (`id`, `email`, `name`, `picture`, `locale`) from Google's UserInfo endpoint upon sign-in.
|
|
18
|
-
* **🔄 Transparent Token Refreshing:** Automatically checks token expiration and uses Google's `refresh_token` endpoint if the access token is within 60 seconds of expiry.
|
|
19
|
-
* **💾 Pluggable Storage:** Use `createInMemoryGoogleTokenStore()` (default) or `createGoogleAuthTokenStore(storage)` for persistent storage (AsyncStorage, MMKV, SecureStore, etc.).
|
|
20
|
-
* **⚛️ First-Class React Hook:** `useGoogleAuth()` provides reactive user state, sign-in, sign-out, and auto-subscriptions.
|
|
21
|
-
* **☁️ Google Drive Backup Synergy:** Pair with `local-lite/backups` to back up and restore SQLite database snapshots directly to the user's Google Drive using the same authenticated session.
|
|
22
|
-
|
|
23
|
-
---
|
|
24
|
-
|
|
25
|
-
## 🚀 Quickstart in Expo / React Native
|
|
26
|
-
|
|
27
|
-
### 1. Install Dependencies
|
|
28
|
-
|
|
29
|
-
```bash
|
|
30
|
-
npx expo install expo-web-browser expo-linking
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
### 2. Configure Google Cloud Console
|
|
34
|
-
|
|
35
|
-
1. Go to the [Google Cloud Console](https://console.cloud.google.com/apis/credentials).
|
|
36
|
-
2. Create an **OAuth 2.0 Client ID** (select **Web application** or native app depending on your redirect flow).
|
|
37
|
-
3. Add your app's redirect URI (e.g. `myapp://oauth` or `https://auth.expo.io/@yourname/myapp`).
|
|
38
|
-
|
|
39
|
-
### 3. Initialize `GoogleAuthClient`
|
|
40
|
-
|
|
41
|
-
Create a shared authentication instance:
|
|
42
|
-
|
|
43
|
-
```typescript
|
|
44
|
-
// auth.ts
|
|
45
|
-
import * as WebBrowser from 'expo-web-browser';
|
|
46
|
-
import * as Linking from 'expo-linking';
|
|
47
|
-
import { GoogleAuthClient, createGoogleAuthTokenStore } from 'local-lite/auth';
|
|
48
|
-
|
|
49
|
-
// Tell WebBrowser to complete any pending auth sessions on web/native
|
|
50
|
-
WebBrowser.maybeCompleteAuthSession();
|
|
51
|
-
|
|
52
|
-
export const googleAuth = new GoogleAuthClient({
|
|
53
|
-
clientId: process.env.EXPO_PUBLIC_GOOGLE_CLIENT_ID || 'YOUR_CLIENT_ID.apps.googleusercontent.com',
|
|
54
|
-
redirectUri: Linking.createURL('oauth'),
|
|
55
|
-
scopes: ['openid', 'email', 'profile'],
|
|
56
|
-
authorize: async ({ authorizationUrl, redirectUri }) => {
|
|
57
|
-
const result = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
|
|
58
|
-
if (result.type !== 'success' || !result.url) {
|
|
59
|
-
return null; // User cancelled
|
|
60
|
-
}
|
|
61
|
-
const callback = new URL(result.url);
|
|
62
|
-
return {
|
|
63
|
-
code: callback.searchParams.get('code') ?? '',
|
|
64
|
-
state: callback.searchParams.get('state') ?? '',
|
|
65
|
-
};
|
|
66
|
-
},
|
|
67
|
-
});
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
---
|
|
71
|
-
|
|
72
|
-
## ⚛️ React Integration with `useGoogleAuth`
|
|
73
|
-
|
|
74
|
-
Use the `useGoogleAuth` hook to bind user login state directly to your UI:
|
|
75
|
-
|
|
76
|
-
```tsx
|
|
77
|
-
import React from 'react';
|
|
78
|
-
import { View, Text, Button, Image, StyleSheet } from 'react-native';
|
|
79
|
-
import { useGoogleAuth } from 'local-lite/react';
|
|
80
|
-
import { googleAuth } from './auth';
|
|
81
|
-
|
|
82
|
-
export function UserHeader() {
|
|
83
|
-
const { user, isSignedIn, loading, signIn, signOut } = useGoogleAuth(googleAuth);
|
|
84
|
-
|
|
85
|
-
if (loading) {
|
|
86
|
-
return <Text style={styles.status}>Checking authentication...</Text>;
|
|
87
|
-
}
|
|
88
|
-
|
|
89
|
-
if (!isSignedIn || !user) {
|
|
90
|
-
return (
|
|
91
|
-
<View style={styles.card}>
|
|
92
|
-
<Text style={styles.title}>Guest Mode</Text>
|
|
93
|
-
<Text style={styles.subtitle}>Sign in with Google to enable cloud backups.</Text>
|
|
94
|
-
<Button title="Sign In with Google" onPress={signIn} />
|
|
95
|
-
</View>
|
|
96
|
-
);
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
return (
|
|
100
|
-
<View style={styles.card}>
|
|
101
|
-
{user.picture && (
|
|
102
|
-
<Image source={{ uri: user.picture }} style={styles.avatar} />
|
|
103
|
-
)}
|
|
104
|
-
<View style={styles.info}>
|
|
105
|
-
<Text style={styles.name}>{user.name}</Text>
|
|
106
|
-
<Text style={styles.email}>{user.email}</Text>
|
|
107
|
-
</View>
|
|
108
|
-
<Button title="Sign Out" onPress={signOut} color="#ef4444" />
|
|
109
|
-
</View>
|
|
110
|
-
);
|
|
111
|
-
}
|
|
112
|
-
|
|
113
|
-
const styles = StyleSheet.create({
|
|
114
|
-
card: { padding: 16, borderRadius: 12, backgroundColor: '#f8fafc', marginBottom: 12 },
|
|
115
|
-
status: { padding: 16, color: '#64748b' },
|
|
116
|
-
avatar: { width: 44, height: 44, borderRadius: 22, marginBottom: 8 },
|
|
117
|
-
title: { fontSize: 16, fontWeight: '700', color: '#0f172a' },
|
|
118
|
-
subtitle: { fontSize: 13, color: '#64748b', marginBottom: 10 },
|
|
119
|
-
info: { marginBottom: 10 },
|
|
120
|
-
name: { fontSize: 15, fontWeight: '600', color: '#0f172a' },
|
|
121
|
-
email: { fontSize: 13, color: '#64748b' },
|
|
122
|
-
});
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
---
|
|
126
|
-
|
|
127
|
-
## 💾 Persistent Token & Profile Storage
|
|
128
|
-
|
|
129
|
-
By default, `GoogleAuthClient` stores credentials in memory. To keep users signed in across app restarts, pass a key-value storage adapter (such as `AsyncStorage` or `expo-secure-store`):
|
|
130
|
-
|
|
131
|
-
```typescript
|
|
132
|
-
import AsyncStorage from '@react-native-async-storage/async-storage';
|
|
133
|
-
import { GoogleAuthClient, createGoogleAuthTokenStore } from 'local-lite/auth';
|
|
134
|
-
|
|
135
|
-
const persistentStore = createGoogleAuthTokenStore({
|
|
136
|
-
getItem: async (key) => {
|
|
137
|
-
const value = await AsyncStorage.getItem(key);
|
|
138
|
-
return value ? JSON.parse(value) : null;
|
|
139
|
-
},
|
|
140
|
-
setItem: async (key, value) => {
|
|
141
|
-
await AsyncStorage.setItem(key, JSON.stringify(value));
|
|
142
|
-
},
|
|
143
|
-
removeItem: async (key) => {
|
|
144
|
-
await AsyncStorage.removeItem(key);
|
|
145
|
-
},
|
|
146
|
-
}, 'my-app-auth');
|
|
147
|
-
|
|
148
|
-
export const googleAuth = new GoogleAuthClient({
|
|
149
|
-
clientId: 'YOUR_CLIENT_ID.apps.googleusercontent.com',
|
|
150
|
-
redirectUri: 'myapp://oauth',
|
|
151
|
-
tokenStore: persistentStore,
|
|
152
|
-
authorize: openBrowserSession,
|
|
153
|
-
});
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
---
|
|
157
|
-
|
|
158
|
-
## ☁️ Google Drive Backup Synergy
|
|
159
|
-
|
|
160
|
-
If you request the `'https://www.googleapis.com/auth/drive.file'` scope during login, the same `GoogleAuthClient` can power SQLite database backups to Google Drive without requiring the user to authenticate a second time:
|
|
161
|
-
|
|
162
|
-
```typescript
|
|
163
|
-
import { GoogleAuthClient } from 'local-lite/auth';
|
|
164
|
-
import { createDatabaseBackup, restoreDatabaseBackup } from 'local-lite/backups';
|
|
165
|
-
|
|
166
|
-
export const googleAuth = new GoogleAuthClient({
|
|
167
|
-
clientId: 'YOUR_CLIENT_ID.apps.googleusercontent.com',
|
|
168
|
-
redirectUri: 'myapp://oauth',
|
|
169
|
-
scopes: [
|
|
170
|
-
'openid',
|
|
171
|
-
'email',
|
|
172
|
-
'profile',
|
|
173
|
-
'https://www.googleapis.com/auth/drive.file', // Request Drive access
|
|
174
|
-
],
|
|
175
|
-
authorize: openBrowserSession,
|
|
176
|
-
});
|
|
177
|
-
|
|
178
|
-
// Create Google Drive storage powered by the authenticated user's session
|
|
179
|
-
const driveStorage = googleAuth.createDriveBackupStorage();
|
|
180
|
-
|
|
181
|
-
// Export SQLite database to Google Drive
|
|
182
|
-
export async function backupToDrive(databaseAdapter) {
|
|
183
|
-
const fileName = await createDatabaseBackup(databaseAdapter, driveStorage);
|
|
184
|
-
console.log(`Database saved to Google Drive: ${fileName}`);
|
|
185
|
-
}
|
|
186
|
-
|
|
187
|
-
// List and restore backups
|
|
188
|
-
export async function restoreFromDrive(databaseAdapter, fileName) {
|
|
189
|
-
const backups = await driveStorage.list();
|
|
190
|
-
console.log('Available backups on Drive:', backups);
|
|
191
|
-
await restoreDatabaseBackup(databaseAdapter, driveStorage, fileName);
|
|
192
|
-
}
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
---
|
|
196
|
-
|
|
197
|
-
## 📖 API Reference
|
|
198
|
-
|
|
199
|
-
### `GoogleAuthClientOptions`
|
|
200
|
-
|
|
201
|
-
| Option | Type | Default | Description |
|
|
202
|
-
| :--- | :--- | :--- | :--- |
|
|
203
|
-
| `clientId` | `string` | *(Required)* | Google OAuth 2.0 Web or Native client ID. |
|
|
204
|
-
| `redirectUri` | `string` | *(Required)* | Redirect callback URI registered in Google Console. |
|
|
205
|
-
| `scopes` | `string[]` | `['openid', 'email', 'profile']` | OAuth scopes to request from Google. |
|
|
206
|
-
| `authorize` | `(req) => Promise<res \| null>` | *(Required)* | Function that opens the system browser session and returns code + state. |
|
|
207
|
-
| `tokenStore` | `GoogleAuthTokenStore` | In-memory store | Token & profile storage adapter. |
|
|
208
|
-
| `prompt` | `'select_account' \| 'consent' \| 'none'` | `'select_account'` | Google consent prompt behavior. |
|
|
209
|
-
| `accessType` | `'offline' \| 'online'` | `'offline'` | Requests a refresh token when set to `'offline'`. |
|
|
210
|
-
|
|
211
|
-
### `GoogleUser`
|
|
212
|
-
|
|
213
|
-
```typescript
|
|
214
|
-
export interface GoogleUser {
|
|
215
|
-
id: string; // Google sub identifier
|
|
216
|
-
email: string; // User's verified email address
|
|
217
|
-
emailVerified: boolean;
|
|
218
|
-
name: string; // Full name
|
|
219
|
-
givenName?: string; // First name
|
|
220
|
-
familyName?: string; // Last name
|
|
221
|
-
picture?: string; // Avatar URL
|
|
222
|
-
locale?: string; // Preferred language/locale
|
|
223
|
-
}
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
### `GoogleAuthClient` Methods
|
|
227
|
-
|
|
228
|
-
* **`signIn(): Promise<GoogleUser | null>`**: Starts PKCE authorization flow, exchanges code for tokens, fetches user profile, and notifies listeners. Returns `null` if user cancels.
|
|
229
|
-
* **`signOut(): Promise<void>`**: Clears stored tokens and cached profile, notifying all subscribers.
|
|
230
|
-
* **`isSignedIn(): Promise<boolean>`**: Checks whether a valid or refreshable session exists.
|
|
231
|
-
* **`getUser(): Promise<GoogleUser | null>`**: Returns the current signed-in user profile, reading from cache or fetching via valid access token.
|
|
232
|
-
* **`getValidAccessToken(): Promise<string>`**: Returns a fresh access token, automatically refreshing if expired or expiring within 60 seconds.
|
|
233
|
-
* **`onAuthStateChange(listener): () => void`**: Subscribes to auth status changes (`GoogleUser | null`). Returns an unsubscribe function.
|
|
234
|
-
* **`createDriveBackupStorage(): GoogleDriveBackupStorage`**: Returns a `GoogleDriveBackupStorage` instance ready for use with `createDatabaseBackup()` / `restoreDatabaseBackup()`.
|
package/docs/index.html
DELETED
|
@@ -1,166 +0,0 @@
|
|
|
1
|
-
<!DOCTYPE html>
|
|
2
|
-
<html lang="en">
|
|
3
|
-
|
|
4
|
-
<head>
|
|
5
|
-
<meta charset="UTF-8">
|
|
6
|
-
<title>Offline-First SQLite Sync Engine</title>
|
|
7
|
-
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
|
|
8
|
-
<meta name="description"
|
|
9
|
-
content="Never let a lost connection break a promise. Local-first sync engine for Expo, React Native, and Node.js.">
|
|
10
|
-
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
|
|
11
|
-
<link rel="icon"
|
|
12
|
-
href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220%22%20viewBox=%220%200%20100%20100%22><text y=%22.9em%22 font-size=%2290%22>⚡</text></svg>">
|
|
13
|
-
|
|
14
|
-
<!-- Fonts -->
|
|
15
|
-
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
16
|
-
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
17
|
-
<link
|
|
18
|
-
href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
|
|
19
|
-
rel="stylesheet">
|
|
20
|
-
|
|
21
|
-
<!-- Docsify Theme & Dark/Light Switcher -->
|
|
22
|
-
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/style.min.css">
|
|
23
|
-
<style>
|
|
24
|
-
:root {
|
|
25
|
-
--docsify-font-family: 'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
|
|
26
|
-
--code-font-family: 'JetBrains Mono', Consolas, Monaco, monospace;
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
body {
|
|
30
|
-
font-family: var(--docsify-font-family);
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
code,
|
|
34
|
-
pre {
|
|
35
|
-
font-family: var(--code-font-family) !important;
|
|
36
|
-
}
|
|
37
|
-
|
|
38
|
-
.sidebar {
|
|
39
|
-
font-weight: 500;
|
|
40
|
-
}
|
|
41
|
-
|
|
42
|
-
.app-name {
|
|
43
|
-
display: none !important;
|
|
44
|
-
}
|
|
45
|
-
|
|
46
|
-
.markdown-section h1 {
|
|
47
|
-
font-weight: 800;
|
|
48
|
-
letter-spacing: -0.025em;
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
.markdown-section h2 {
|
|
52
|
-
font-weight: 700;
|
|
53
|
-
letter-spacing: -0.02em;
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
.docsify-pagination-container {
|
|
57
|
-
margin-top: 2.5rem;
|
|
58
|
-
padding-top: 1.25rem;
|
|
59
|
-
border-top: 1px solid rgba(148, 163, 184, 0.15);
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
.pagination-item {
|
|
63
|
-
max-width: 45%;
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
.pagination-item a {
|
|
67
|
-
text-decoration: none !important;
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
.pagination-item-label {
|
|
71
|
-
font-size: 0.72rem !important;
|
|
72
|
-
font-weight: 600 !important;
|
|
73
|
-
letter-spacing: 0.05em;
|
|
74
|
-
text-transform: uppercase;
|
|
75
|
-
opacity: 0.65;
|
|
76
|
-
}
|
|
77
|
-
|
|
78
|
-
.pagination-item-title {
|
|
79
|
-
font-size: 0.95rem !important;
|
|
80
|
-
font-weight: 600 !important;
|
|
81
|
-
margin-top: 0.15rem;
|
|
82
|
-
line-height: 1.35 !important;
|
|
83
|
-
}
|
|
84
|
-
</style>
|
|
85
|
-
</head>
|
|
86
|
-
|
|
87
|
-
<body>
|
|
88
|
-
<div id="app">Loading documentation...</div>
|
|
89
|
-
<script>
|
|
90
|
-
window.$docsify = {
|
|
91
|
-
name: 'Local Lite',
|
|
92
|
-
repo: 'https://github.com/georgechitechi/local-lite',
|
|
93
|
-
loadSidebar: true,
|
|
94
|
-
subMaxLevel: 3,
|
|
95
|
-
auto2top: true,
|
|
96
|
-
homepage: 'README.md',
|
|
97
|
-
search: {
|
|
98
|
-
maxAge: 86400000,
|
|
99
|
-
paths: 'auto',
|
|
100
|
-
placeholder: 'Search documentation...',
|
|
101
|
-
noData: 'No results found',
|
|
102
|
-
depth: 4
|
|
103
|
-
},
|
|
104
|
-
copyCode: {
|
|
105
|
-
buttonText: 'Copy',
|
|
106
|
-
successText: 'Copied!'
|
|
107
|
-
},
|
|
108
|
-
darklightTheme: {
|
|
109
|
-
siteFont: 'Inter',
|
|
110
|
-
defaultTheme: 'dark',
|
|
111
|
-
codeFontFamily: 'JetBrains Mono',
|
|
112
|
-
bodyFontSize: '15px',
|
|
113
|
-
dark: {
|
|
114
|
-
accent: '#38bdf8',
|
|
115
|
-
toogleBackground: '#ffffff',
|
|
116
|
-
background: '#090d16',
|
|
117
|
-
textColor: '#e2e8f0',
|
|
118
|
-
codeTextColor: '#f8fafc',
|
|
119
|
-
codeBackgroundColor: '#0f172a',
|
|
120
|
-
borderColor: '#1e293b',
|
|
121
|
-
blockQuoteColor: '#38bdf8',
|
|
122
|
-
highlightColor: '#f59e0b',
|
|
123
|
-
sidebarSublabel: '#94a3b8'
|
|
124
|
-
},
|
|
125
|
-
light: {
|
|
126
|
-
accent: '#0284c7',
|
|
127
|
-
toogleBackground: '#0f172a',
|
|
128
|
-
background: '#ffffff',
|
|
129
|
-
textColor: '#0f172a',
|
|
130
|
-
codeTextColor: '#0f172a',
|
|
131
|
-
codeBackgroundColor: '#f8fafc',
|
|
132
|
-
borderColor: '#e2e8f0',
|
|
133
|
-
blockQuoteColor: '#0284c7',
|
|
134
|
-
highlightColor: '#f59e0b',
|
|
135
|
-
sidebarSublabel: '#64748b'
|
|
136
|
-
}
|
|
137
|
-
},
|
|
138
|
-
pagination: {
|
|
139
|
-
previousText: 'Previous',
|
|
140
|
-
nextText: 'Next',
|
|
141
|
-
crossChapter: true,
|
|
142
|
-
crossChapterText: true
|
|
143
|
-
}
|
|
144
|
-
}
|
|
145
|
-
</script>
|
|
146
|
-
<!-- Docsify Core -->
|
|
147
|
-
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
|
|
148
|
-
|
|
149
|
-
<!-- Plugins -->
|
|
150
|
-
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
|
|
151
|
-
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
|
|
152
|
-
<script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script>
|
|
153
|
-
<script src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js"></script>
|
|
154
|
-
|
|
155
|
-
<!-- Prism Syntax Highlighting -->
|
|
156
|
-
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
|
|
157
|
-
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-typescript.min.js"></script>
|
|
158
|
-
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-javascript.min.js"></script>
|
|
159
|
-
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
|
|
160
|
-
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-sql.min.js"></script>
|
|
161
|
-
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-jsx.min.js"></script>
|
|
162
|
-
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-tsx.min.js"></script>
|
|
163
|
-
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-markdown.min.js"></script>
|
|
164
|
-
</body>
|
|
165
|
-
|
|
166
|
-
</html>
|