gbaas_sdk 3.1.0

Dart SDK for BaaS (Backend as a Service) - auth, database, storage, realtime, functions, admin APIs.

3.1.0 — 2026-07-28

Protocolo por TÓPICO del hub realtime, agregado sin tocar la API por tabla: las apps publicadas siguen funcionando igual.

Added

• Realtime por tópico: subscribeTopic(topic, cb) devuelve la misma RealtimeSubscription cancelable de siempre, y publishTopic(topic, payload) publica hacia el hub (la ubicación del conductor viaja por acá, autorizada server-side, en vez de por un canal broadcast sin authz).
• Detección del router: el cliente lee GET /api/config → realtime.router y habla el protocolo que ese servidor entiende. Si el campo no está, la red falla o el valor es desconocido, cae a legacy — el default SEGURO: un cliente que asuma tópicos contra un servidor legacy queda mudo.
• Estado de conexión observable + señal de reconectado (solo desde la segunda conexión: la primera no perdió nada). Es lo que permite refetchear al volver, porque el socket no guarda lo que pasó mientras estuvo caído.
• Frames de control propagados: subscribe_denied y subscription_revoked llegan al llamador en vez de morir en silencio — un tópico denegado es un bug de permisos que hay que ver.

Notes

• Las suscripciones por tópico se re-registran solas al reconectar, igual que las de tabla.
• El socket sigue siendo LATENCIA, no garantía: el push server-side es el que garantiza la entrega de una oferta.

3.0.0 — 2026-06-05

Validated end-to-end (32 live checks) against a running golang-baas server.

BREAKING CHANGES

• auth.verifyMfa({ tempToken }) → auth.verifyMfa({ mfaToken }). The backend reads mfa_token; the old tempToken was never sent, so MFA login could not complete.
• auth.enableMfa({ code }) → auth.enableMfa({ required String secret, required String code }). The backend re-validates the TOTP code against the setup secret. Pass the secret from setupMfa().
• Removed storage.moveFile(...) and storage.copyFile(...) — the backend has no move/copy routes (they always 404'd).
• storage.deleteFiles({ bucket, paths }) → storage.deleteFilesByIds(List<String> ids).

Added

• database.rpc(fn, { params, get }) — invoke PL/pgSQL functions (PostgREST .rpc() parity).
• QueryBuilder: contains/containedBy/overlaps (cs/cd/ov), textSearch (fts/plfts/phfts/wfts), not(condition), and/notAnd/notOr groups, QueryBuilder.cond(...), multi-column orderBy, working count() (Prefer:count=exact → Content-Range), insertMany(), deleteWhere().
• Auth: signInAnonymously(), requestOtp(...), verifyOtp(...), upgradeToAccount(...).
• RateLimitException (HTTP 429) with a parsed retry hint.

Fixed

• executeRawSql() reads the { "data": ... } envelope (previously read a non-existent rows key and dropped every row).
• functions.executeCode() parses duration_ms/logs; functions.update() upserts by name (no PUT route exists).
• storage.download() streams via the backend download route; getFile/download/delete return 404 instead of a null-pointer 500.
• RLS denials surface as 403, malformed ids as 400 (instead of 500).

2.0.0 — 2026-05-22

BREAKING CHANGES

• Renamed from(table).inList(col, values) to from(table).inFilter(col, values). The old name emitted broken ?col=inList.[a, b] syntax — the server silently ignored it and returned zero rows. The new method emits the PostgREST-correct ?col=in.(a,b) (values containing ,, (, ), or " are wrapped in double quotes).
• storage.upload(bucket: ...) now sends the multipart field bucket_id instead of bucket and preserves the path field. Calls that depended on the previous (broken) behavior landed files in the server's default bucket — re-verify destinations after upgrading.
• storage.getFile(id) now returns StorageFileWithUrl (metadata + presigned URL) instead of StorageFile. Access metadata via .file and the 15-minute presigned URL via .url.
• Removed auth.updateProfile(...) (called PUT /api/users/me, a route the backend never implemented). The only working update endpoint is the admin PUT /api/users/{id} and that does not belong on the self-service AuthClient surface.
• auth.restoreSession() now optionally reads its token from SessionStorage when no argument is provided; the token parameter became positional+optional.
• BaasClient.setAccessToken and clearAuth are now async (they persist through SessionStorage).
• New BaasClient constructor parameter sessionStorage (defaults to InMemorySessionStorage).

Security

• Fixed validateResetToken returning true for both valid and invalid tokens — the backend always responds 200 with {"valid": bool}, so the previous "did it 200?" check passed everything through. Anyone shipping a password-reset UI built on 1.x should upgrade.

Added

• BaasClient.onAuthStateChange broadcast stream emitting AuthState.signedIn, signedOut, sessionExpired.
• SessionStorage interface (+ default InMemorySessionStorage) for pluggable token persistence. Flutter apps wire flutter_secure_storage/shared_preferences via an adapter — keeps the SDK pure Dart.
• Centralized 401 handling: any authenticated request that comes back 401 clears the local + persisted session, emits sessionExpired + signedOut, and throws a new UnauthorizedException (subtype of AuthException). A 401 without a token (i.e. login with bad creds) stays as a plain AuthException with no side effects.
• Realtime: parser for concatenated JSON frames ({}{}{} in a single WebSocket message) honoring strings/escapes.

Fixed

• getProfile() and restoreSession() now call the real GET /api/profile route instead of the phantom /api/users/me.
• Query builder operators isNull, isNotNull emit is.null / not.is.null (PostgREST syntax) instead of isNull.null.
• example/main.dart now compiles against the 2.0 API and demonstrates onAuthStateChange.

Documented

• Realtime backend limitation (role=admin is the only role that currently receives events) is now explicitly noted on RealtimeClient and subscribe() dartdoc, and in KNOWN_ISSUES.md.

Known issues (tracked for v2.1+)

• Several auth methods (setupMfa, enableMfa, verifyMfa, OAuth provider config) remain on the API surface but their server-side counterparts have shape mismatches not addressed in 2.0.0. See KNOWN_ISSUES.md.

1.0.4

• Fixed: await WebSocket handshake (channel.ready) before marking connected
• Added: 30s heartbeat ping to detect dead connections
• Added: Cache-Control: no-cache header on all GET requests to bypass stale Redis cache
• Fixed: increased max reconnect attempts from 5 to 10
• Removed: dead subscribe/unsubscribe messages (server broadcasts all events)
• Fixed: auto-disconnect when last subscription removed
• Fixed: proper cleanup of channel/timers on error and disconnect

1.0.3

• Fixed Dart SDK constraint to >=3.0.0
• Updated web_socket_channel to support v2.x and v3.x

1.0.2

• Minor fixes

1.0.1

• Updated web_socket_channel to support v2.x and v3.x
• Updated README with complete documentation for all 23 modules

1.0.0

• Initial release
• Auth: login, register, MFA, OAuth, password reset, email verification
• Database: CRUD, query builder with filters, raw SQL, export
• Storage: upload, download, buckets, presigned URLs
• Realtime: WebSocket subscriptions with auto-reconnect
• Functions: edge function execution, hooks
• Admin: webhooks, policies, API keys, backups, migrations, email, jobs, env vars, branches, log drains, audit, metrics, IP whitelist, CORS origins, environments, search, users, GraphQL