@groveback/sdk

End-user JavaScript/TypeScript client for Groveback — an open-source Backend-as-a-Service over MongoDB. Auth (email/password, MFA, OAuth), per-collection CRUD gated by server-side policies, file storage, realtime subscriptions, vector search, and GraphQL. Zero dependencies; works in the browser, Node ≥ 18, and Bun.

Install

npm install @groveback/sdk
# or
bun add @groveback/sdk

Quick start

import { createClient } from '@groveback/sdk';

const grove = createClient({
  baseUrl: 'https://api.example.com', // your Groveback instance ("/api/v1" is appended)
  projectId: 'my-project',            // project id or slug
});

// Auth
await grove.auth.register('[email protected]', 'hunter22', 'Ada');
const user = await grove.auth.login('[email protected]', 'hunter22');
// If the account has MFA, login resolves { mfaRequired: true } — finish with:
// await grove.auth.verifyMfa('123456');

// Data (policy-gated on the server)
const posts = grove.collection('posts');
const created = await posts.create({ title: 'hello', body: '...' });
const list = await posts.find({ filter: { title: 'hello' }, limit: 10 });
await posts.update(created._id as string, { body: 'edited' }); // PATCH ($set)
await posts.delete(created._id as string);

// Realtime
const stop = posts.subscribe('*', (event) => {
  console.log(event.type, event.document);
});
stop(); // unsubscribe

// Storage
await grove.storage.upload('avatars', 'ada.png', fileBlob, 'image/png');

// GraphQL
const data = await grove.graphql<{ posts: { title: string }[] }>('{ posts { title } }');

Server-to-server (API key)

const grove = createClient({
  baseUrl: 'https://api.example.com',
  projectId: 'my-project',
  apiKey: 'gb_sk_...', // every request authenticates with the key; auth.* is unused
});

Token persistence

Access/refresh tokens live in memory. To persist sessions, hydrate and observe them:

const grove = createClient({
  baseUrl,
  projectId,
  onTokensChanged: (tokens) => localStorage.setItem('gb', JSON.stringify(tokens)),
});
const saved = localStorage.getItem('gb');
if (saved) grove.auth.setTokens(JSON.parse(saved));

On a 401 the client transparently refreshes once and retries; a failed refresh clears the tokens and rethrows.

OAuth

// Start: navigate the user to the provider
location.href = grove.auth.oauthStartUrl('google', location.origin + '/oauth/done');
// Finish: on the redirect page
const user = await grove.auth.completeOAuth(location.hash);

Errors

Non-2xx responses throw ApiError { status, code, message }.

License

Apache-2.0