@zuzjs/flare 0.2.4 → 0.2.6

package/README.md

@@ -1,58 +1,300 @@
-# 🔥 ZuzFlare Client
+# ZuzFlare Client
 
-> Official JavaScript/TypeScript client for ZuzFlare Server
+Official JavaScript/TypeScript client for ZuzFlare Server.
 
 [![npm version](https://badge.fury.io/js/%40zuzjs%2Fflare.svg)](https://www.npmjs.com/package/@zuzjs/flare)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Real-time database client with Firebase-like API for your self-hosted ZuzFlare server.
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @zuzjs/flare
 ```
 
-## 🚀 Quick Start
+## Maintainer Rule
 
-```typescript
-import { FlareClient } from '@zuzjs/flare';
+When adding or changing any public SDK API, update this README in the same commit and add a usage example for that API.
 
-const flare = new FlareClient({
-  endpoint: 'http://localhost:5050',
-  appId: 'my-app'
-});
+## Quick Start
+
+```ts
+import { connectApp } from '@zuzjs/flare';
 
-flare.connect();
+const app = connectApp({
+  endpoint: 'https://flare.zuzcdn.net',
+  appId: 'my-app',
+  apiKey: 'app-api-key',
+});
 
-// Write data
-await flare.collection('users').doc('alice').set({
+await app.collection('users').doc('alice').set({
   name: 'Alice',
-  email: 'alice@example.com'
+  email: 'alice@example.com',
+});
+
+app.collection('users').onSnapshot((snapshot) => {
+  console.log('snapshot', snapshot);
+});
+```
+
+## Public API Usage Examples
+
+### Core Instance
+
+```ts
+import { connectApp, getFlare, disconnectFlare } from '@zuzjs/flare';
+
+const app = connectApp({ endpoint: 'https://flare.zuzcdn.net', appId: 'my-app', apiKey: 'ak' });
+const same = getFlare();
+disconnectFlare();
+```
+
+### Auth Config And State
+
+```ts
+const app = connectApp({ endpoint: 'https://flare.zuzcdn.net', appId: 'my-app', apiKey: 'ak' });
+
+await app.ensureCsrfProtection();
+const config = await app.loadAuthConfig();
+
+const offConfig = app.onAuthConfigLoaded((next) => {
+  console.log('auth config loaded', next.providers);
+});
+
+const offState = app.onAuthStateChanged((session) => {
+  console.log('auth state', session?.uid);
+});
+
+const legacyOffState = app.onAuthStateChange((session) => {
+  console.log('legacy listener', session?.uid);
+});
+
+console.log('csrf cookie name', app.getCsrfCookieName());
+console.log('csrf token', app.getCsrfToken());
+console.log('current user', app.getCurrentUser());
+
+offConfig();
+offState();
+legacyOffState();
+```
+
+### Email Password Auth
+
+```ts
+const app = connectApp({ endpoint: 'https://flare.zuzcdn.net', appId: 'my-app', apiKey: 'ak' });
+
+await app.createUserWithEmail('alice@example.com', 'StrongPassword123!');
+await app.createUserWithEmailAndPassword('bob@example.com', 'StrongPassword123!');
+
+await app.signInWithEmail('alice@example.com', 'StrongPassword123!');
+await app.signInWithEmailAndPassword('bob@example.com', 'StrongPassword123!');
+
+await app.signInOrCreateWithEmail('carol@example.com', 'StrongPassword123!');
+await app.signInOrCreateWithEmailAndPassword('dave@example.com', 'StrongPassword123!');
+
+await app.auth('<access-token>');
+await app.refreshAuthSession();
+await app.signOut();
+```
+
+### Email Verification And Recovery
+
+```ts
+const app = connectApp({ endpoint: 'https://flare.zuzcdn.net', appId: 'my-app', apiKey: 'ak' });
+
+const verifySent = await app.sendEmailVerification('alice@example.com');
+await app.verifyEmailWithCode('alice@example.com', '123456');
+await app.confirmEmailLink('<link-token>', 'alice@example.com');
+
+const recoverySent = await app.sendAccountRecovery('alice@example.com');
+await app.recoverAccountWithCode('alice@example.com', '123456', 'NextStrongPassword123!');
+await app.recoverAccountWithToken('<recovery-token>', 'NextStrongPassword123!');
+
+console.log(verifySent, recoverySent);
+```
+
+### OAuth Helpers
+
+```ts
+const app = connectApp({ endpoint: 'https://flare.zuzcdn.net', appId: 'my-app', apiKey: 'ak' });
+
+await app.signIn('google');
+await app.signInWithGoogle();
+await app.signInWithGitHub();
+await app.signInWithFacebook();
+await app.signInWithDropbox();
+
+const redirectResult = await app.handleSignInRedirect();
+console.log('oauth redirect result', redirectResult);
+```
+
+### SSR Token
+
+```ts
+const app = connectApp({ endpoint: 'https://flare.zuzcdn.net', appId: 'my-app', apiKey: 'ak' });
+
+const ssr = await app.issueSsrToken(120);
+console.log(ssr.token, ssr.expires_in);
+```
+
+### Push APIs
+
+```ts
+const app = connectApp({ endpoint: 'https://flare.zuzcdn.net', appId: 'my-app', apiKey: 'ak' });
+
+await app.setupPushServiceWorker();
+await app.requestPushPermission();
+
+const { token } = await app.acquireBrowserPushToken();
+await app.registerPushToken({ token, platform: 'web', topics: ['news'] });
+
+await app.enableBrowserPush({ topics: ['marketing'] });
+
+await app.sendPushNotification({
+  title: 'Hello',
+  body: 'Welcome back',
+  topic: 'news',
 });
 
-// Real-time updates
-flare.collection('users').onSnapshot((data) => {
-  console.log('Users:', data);
+await app.unregisterPushToken(token);
+```
+
+### Direct Query Helpers (Knex-Style)
+
+`collection()` query chaining uses object-based logical steps and dedicated operator families:
+
+- Logic: `where({...})`, `and({...})`, `or({...})`
+- `in` family: `in`, `andIn`, `orIn`
+- `notIn` family: `notIn`, `andNotIn`, `orNotIn`
+- `arrayContains` family: `arrayContains`, `andArrayContains`, `orArrayContains`
+- `arrayContainsAny` family: `arrayContainsAny`, `andArrayContainsAny`, `orArrayContainsAny`
+- `some` family (array of objects): `some`, `andSome`, `orSome`
+- `like` family: `like`, `andLike`, `orLike`
+- `notLike` family: `notLike`, `andNotLike`, `orNotLike`
+- `exists` family: `exists`, `andExists`, `orExists`
+- `notExists` family: `notExists`, `andNotExists`, `orNotExists`
+
+```ts
+const uid = 'bDEgnSqsEDT5qdDdtOX1';
+
+const boards = await app
+  .collection('boards')
+  .where({ uid })
+  .orArrayContains('team', uid)
+  .orderBy('createdAt', 'desc')
+  .limit(20)
+  .get();
+
+const sameBoards = await app
+  .collection('boards')
+  .where({ uid })
+  .orArrayContains('team', uid)
+  .get();
+
+const active = await app
+  .collection('tasks')
+  .in('status', ['todo', 'doing'])
+  .andArrayContainsAny('labels', ['urgent', 'backend'])
+  .andLike('title', '%bug%')
+  .get();
+
+const boardAccess = await app
+  .collection('boards')
+  .some('team', { uid: 'xyz', role: 1 })
+  .get();
+```
+
+### Template-Based Email APIs
+
+### Security Rules Example (Boards Owner Or Team Member)
+
+For a `boards` document shape like:
+
+```json
+{
+  "uid": "ownerUid",
+  "team": ["memberUid1", "memberUid2"]
+}
+```
+
+Use this DSL to allow read for owner or team member, and allow write only for owner:
+
+```txt
+service cloud.firestore {
+  match /databases/{database}/documents {
+    function isOwner(ownerUid) {
+      return auth != null && auth.uid == ownerUid;
+    }
+
+    function isTeamMember(teamUids) {
+      return auth != null && auth.uid in teamUids;
+    }
+
+    match /boards/{boardId} {
+      allow read: if isOwner(resourceData.uid) || isTeamMember(resourceData.team);
+      allow create, update, delete: if isOwner(resourceData.uid);
+    }
+  }
+}
+```
+
+Tip: if you set owner uid at create time, prefer checking `requestData.uid` on create and `resourceData.uid` on update/delete.
+
+Emails are sent only through app-level templates stored in `_flare_email_templates`.
+
+Template placeholders use `{key}` syntax and are replaced from `values`.
+
+If template has `includeVerificationLink: true`, server generates a link in `_flare_email_links` and injects:
+
+- `{verificationLink}`
+- `{verifyUrl}`
+- `{verificationToken}`
+
+```ts
+const app = connectApp({ endpoint: 'https://flare.zuzcdn.net', appId: 'my-app', apiKey: 'ak' });
+
+const sendRes = await app.sendEmail({
+  to: 'alice@example.com',
+  tag: 'team_invite',
+  values: {
+    displayName: 'Alice',
+    inviterName: 'Bob',
+    teamName: 'Product',
+  },
+});
+
+console.log(sendRes.sent, sendRes.tag, sendRes.verifyUrl);
+
+const verifyRes = await app.verifyEmailLink({
+  token: '<token-from-link>',
+  tag: 'team_invite',
+  email: 'alice@example.com',
 });
+
+console.log(verifyRes.verified, verifyRes.tag);
 ```
 
-## 📖 Full Documentation
+## Template Collection Example
 
-See [complete documentation](https://flare.zuz.com.pk) for:
-- API Reference
-- Usage Examples  
-- TypeScript Types
-- React/Vue/Svelte Integration
-- Authentication
-- Offline Support
+Example document in `_flare_email_templates`:
+
+```json
+{
+  "tag": "team_invite",
+  "enabled": true,
+  "subject": "Hi {displayName}, you are invited to {teamName}",
+  "text": "Hello {displayName},\n\n{inviterName} invited you.\n\nOpen: {verificationLink}",
+  "html": "<p>Hello {displayName}</p><p>{inviterName} invited you.</p><p><a href=\"{verificationLink}\">Accept</a></p>",
+  "includeVerificationLink": true,
+  "verifyUrl": "https://app.example.com/accept?token=__TOKEN__&appId=__APP_ID__&tag=__TAG__",
+  "verificationTtlHours": 72
+}
+```
 
-## 🔗 Links
+## Links
 
-- [Server Package](@zuzjs/flare-server)
-- [GitHub](https://github.com/zuzjs/flare-client)
-- [Documentation](https://flare.zuz.com.pk)
+- Server package: @zuzjs/flare-server
+- Documentation: https://flare.zuz.com.pk
 
-## 📄 License
+## License
 
-MIT © Zuz.js Team
+MIT