@flowerforce/flowerbase-client 0.1.0

package/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 Flowerbase

package/README.md

@@ -0,0 +1,209 @@
+# @flowerforce/flowerbase-client
+
+Client TypeScript leggero per usare Flowerbase con API in stile Realm:
+
+- autenticazione (`local-userpass`, `anon-user`, `custom-function`)
+- chiamate funzioni (`user.functions.<name>(...)`)
+- accesso a MongoDB Atlas service (`user.mongoClient("mongodb-atlas")`)
+- change stream via `watch()` con async iterator
+- supporto BSON/EJSON (`ObjectId`, `Date`, ecc.)
+
+## Installazione
+
+```bash
+npm i @flowerforce/flowerbase-client
+```
+
+## Quick start
+
+```ts
+import { App, Credentials } from '@flowerforce/flowerbase-client'
+
+const app = new App({
+  id: 'my-app-id',
+  baseUrl: 'http://localhost:8000',
+  timeout: 10000
+})
+
+await app.logIn(Credentials.emailPassword('user@example.com', 'secret'))
+
+const user = app.currentUser
+if (!user) throw new Error('User not logged in')
+
+const result = await user.functions.myFunction('hello')
+console.log(result)
+```
+
+## Configurazione `App`
+
+```ts
+new App({
+  id: string,          // app id Flowerbase
+  baseUrl: string,     // URL base backend (es: http://localhost:8000)
+  timeout?: number     // default 10000
+})
+```
+
+## Autenticazione
+
+### Local user/pass
+
+```ts
+await app.logIn(Credentials.emailPassword(email, password))
+```
+
+### Anonymous
+
+```ts
+await app.logIn(Credentials.anonymous())
+```
+
+### Custom function auth
+
+```ts
+await app.logIn(
+  Credentials.function({
+    username: 'demo',
+    pin: '1234'
+  })
+)
+```
+
+### Utility `emailPasswordAuth`
+
+```ts
+await app.emailPasswordAuth.registerUser({ email, password })
+await app.emailPasswordAuth.sendResetPasswordEmail(email)
+await app.emailPasswordAuth.callResetPasswordFunction(email, newPassword, extraArg1, extraArg2)
+await app.emailPasswordAuth.resetPassword({ token, tokenId, password })
+```
+
+## Current user
+
+Dopo il login:
+
+```ts
+const user = app.currentUser
+```
+
+Interfaccia principale:
+
+- `user.id`
+- `user.functions.<functionName>(...args)`
+- `user.mongoClient('mongodb-atlas')`
+- `user.refreshAccessToken()`
+- `user.refreshCustomData()`
+- `user.logOut()`
+
+## Funzioni server
+
+```ts
+const response = await user.functions.calculateScore({ workspaceId: 'w1' })
+```
+
+Le risposte sono normalizzate lato client per gestire payload JSON/EJSON.
+
+## Mongo service
+
+```ts
+const mongo = user.mongoClient('mongodb-atlas')
+const collection = mongo.db('mydb').collection('todos')
+
+const one = await collection.findOne({ done: false })
+const many = await collection.find({ done: false })
+
+await collection.insertOne({ title: 'Task', createdAt: new Date() })
+await collection.updateOne({ title: 'Task' }, { $set: { done: true } })
+await collection.deleteOne({ title: 'Task' })
+```
+
+Metodi disponibili su `collection`:
+
+- `find(query?, options?)`
+- `findOne(query?, options?)`
+- `insertOne(document, options?)`
+- `updateOne(filter, update, options?)`
+- `updateMany(filter, update, options?)`
+- `deleteOne(filter, options?)`
+- `watch(options?)`
+
+## Watch / Change streams
+
+`watch()` restituisce un async iterator con reconnect automatico e metodo `close()`.
+
+```ts
+const stream = collection.watch()
+
+try {
+  for await (const change of stream) {
+    console.log(change)
+  }
+} finally {
+  stream.close()
+}
+```
+
+Esempio con filtro Realm-like:
+
+```ts
+const stream = collection.watch({
+  filter: {
+    operationType: 'update',
+    'fullDocument.type': 'perennial'
+  }
+})
+```
+
+## BSON / EJSON
+
+Il client esporta anche:
+
+```ts
+import { BSON, EJSON, ObjectId, ObjectID } from '@flowerforce/flowerbase-client'
+```
+
+Il layer Mongo client serializza query/opzioni con EJSON e deserializza le risposte, così tipi BSON come `ObjectId` e `Date` restano coerenti con l'uso Realm-like.
+
+## Sessione
+
+La sessione (`accessToken`, `refreshToken`, `userId`) viene salvata con chiave:
+
+- `flowerbase:<appId>:session`
+
+Storage usato:
+
+- `localStorage` se disponibile (browser)
+- memory store fallback (ambienti senza `localStorage`)
+
+Su bootstrap dell'app viene tentato un refresh automatico dell'access token usando il refresh token salvato.
+
+## Logout
+
+```ts
+await user.logOut()
+```
+
+Invia `DELETE /auth/session` con refresh token e pulisce la sessione locale.
+
+## Tipi esportati
+
+- `AppConfig`
+- `CredentialsLike`
+- `UserLike`
+- `MongoClientLike`
+- `CollectionLike`
+- `WatchAsyncIterator`
+
+## Build e test (workspace)
+
+```bash
+npm run build --workspace @flowerforce/flowerbase-client
+npm run test --workspace @flowerforce/flowerbase-client
+```
+
+Oppure dal package:
+
+```bash
+npm run build
+npm test
+```

package/dist/app.d.ts

@@ -0,0 +1,85 @@
+import { AppConfig, CredentialsLike, ProfileData, SessionData } from './types';
+import { Credentials } from './credentials';
+import { User } from './user';
+export declare class App {
+    private static readonly appCache;
+    static readonly Credentials: typeof Credentials;
+    readonly id: string;
+    readonly baseUrl: string;
+    readonly timeout: number;
+    private readonly sessionManager;
+    private readonly usersById;
+    private readonly sessionsByUserId;
+    private usersOrder;
+    private readonly profilesByUserId;
+    private readonly sessionBootstrapPromise;
+    private readonly listeners;
+    emailPasswordAuth: {
+        registerUser: (input: {
+            email: string;
+            password: string;
+        }) => Promise<unknown>;
+        confirmUser: (input: {
+            token: string;
+            tokenId: string;
+        }) => Promise<unknown>;
+        resendConfirmationEmail: (input: {
+            email: string;
+        }) => Promise<unknown>;
+        retryCustomConfirmation: (input: {
+            email: string;
+        }) => Promise<unknown>;
+        sendResetPasswordEmail: (input: {
+            email: string;
+        } | string) => Promise<unknown>;
+        callResetPasswordFunction: (input: {
+            email: string;
+            password: string;
+        } | string, passwordOrArg?: string, ...args: unknown[]) => Promise<unknown>;
+        resetPassword: (input: {
+            token: string;
+            tokenId: string;
+            password: string;
+        }) => Promise<unknown>;
+    };
+    constructor(idOrConfig: string | AppConfig);
+    static getApp(appIdOrConfig: string | AppConfig): App;
+    get currentUser(): User | null;
+    get allUsers(): Readonly<Record<string, User>>;
+    private persistSessionsByUser;
+    private persistUsersOrder;
+    private touchUser;
+    private removeUserFromOrder;
+    private setSessionForUser;
+    private clearSessionForUser;
+    private setCurrentSessionFromOrder;
+    private notifyListeners;
+    private providerUrl;
+    private authUrl;
+    private functionsUrl;
+    private createSession;
+    private bootstrapSessionOnLoad;
+    private ensureSessionBootstrapped;
+    private setLoggedInUser;
+    private getOrCreateUser;
+    logIn(credentials: CredentialsLike): Promise<User>;
+    switchUser(nextUser: User): void;
+    removeUser(user: User): Promise<void>;
+    deleteUser(user: User): Promise<void>;
+    getSessionOrThrow(userId?: string): SessionData;
+    getSession(userId?: string): SessionData | null;
+    hasUser(userId: string): boolean;
+    getProfileSnapshot(userId: string): ProfileData | undefined;
+    postProvider<T = unknown>(path: string, body: unknown): Promise<T>;
+    private requestWithAccessToken;
+    callFunction(name: string, args: unknown[], userId?: string): Promise<any>;
+    callFunctionStreaming(name: string, args: unknown[], userId?: string): Promise<AsyncIterable<Uint8Array>>;
+    callService(name: string, args: unknown[], service?: string, userId?: string): Promise<unknown>;
+    getProfile(userId?: string): Promise<ProfileData>;
+    refreshAccessToken(userId?: string): Promise<string>;
+    logoutUser(userId?: string): Promise<void>;
+    addListener(callback: () => void): void;
+    removeListener(callback: () => void): void;
+    removeAllListeners(): void;
+}
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

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