Web SDK

npm install @koolbase/js

import { Koolbase, RestoreResult } from '@koolbase/js';

export async function startKoolbase() {
  await Koolbase.initialize({
    publicKey: 'pk_live_your_key_here',
    baseUrl: 'https://api.koolbase.com',
    analyticsEnabled: true,
    appVersion: '1.0.0',
    authTimeout: 10000, // optional, default 10s
  });

  // Restore a session persisted from a previous visit. Optimistic state is
  // read from storage before any network call, so authenticated UI renders
  // without a round trip.
  const result = await Koolbase.auth.restoreSession();

  switch (result) {
    case RestoreResult.Restored: return 'signed-in';
    case RestoreResult.Offline:  return 'signed-in'; // optimistic, no network yet
    case RestoreResult.Expired:  return 'signed-out';
    case RestoreResult.NoSession: return 'signed-out';
  }
}

import { Koolbase } from '@koolbase/js';

// Two outcomes, and you must tell them apart: with verification required
// on the project, the account is created and NO session is issued.
const result = await Koolbase.auth.register({
  email: '[email protected]',
  password: 'password',
});
if (result.status === 'verification_required') {
  showCheckYourEmail(result.user.email);   // account exists, not signed in
} else {
  showApp();                               // result.session is live
}

const session = await Koolbase.auth.login({
  email: '[email protected]',
  password: 'password',
});

const me = Koolbase.auth.currentUser;

await Koolbase.auth.logout();
await Koolbase.auth.forgotPassword('[email protected]');

// Fires immediately with the current state, then on every change.
const unsubscribe = Koolbase.auth.onAuthStateChange((user) => {
  render(user ? 'signed in' : 'signed out');
});

// Your /verify-email page, with ?token= from the link
await Koolbase.auth.verifyEmail(token);

// Your /reset-password page
await Koolbase.auth.resetPassword(token, newPassword);

// A "resend" button, for a signed-in but unverified user
const result = await Koolbase.auth.resendVerificationEmail();
if (result.alreadyVerified) {
  // They verified in another tab. Not an error — say so and move on.
  showVerified();
}

// A "didn't get it?" link on your check-your-email page
await Koolbase.auth.resendVerificationEmailToAddress(email);
// Show the same message either way — see below

import {
  VerificationResendCooldownError,
  VerificationResendDailyCapError,
} from '@koolbase/js';

try {
  await Koolbase.auth.resendVerificationEmail();
} catch (e) {
  if (e instanceof VerificationResendCooldownError) {
    // e.cooldownUntil is a Date — show a countdown, not a bare refusal
    startCountdown(e.cooldownUntil);
  } else if (e instanceof VerificationResendDailyCapError) {
    showMessage('Try again tomorrow.');
  } else {
    throw e;
  }
}

await Koolbase.auth.sendOtp({ phoneNumber: '+233200000000' });
const result = await Koolbase.auth.verifyOtp({
  phoneNumber: '+233200000000',
  code: '123456',
});
if (result.isNewUser) showOnboarding();

// After your web OAuth flow returns an ID token:
const session = await Koolbase.auth.signInWithGoogle({ idToken });

// Apple, likewise:
const session = await Koolbase.auth.signInWithApple({ identityToken });

import { browserPlatform } from '@koolbase/js';

// 'indexeddb' | 'localstorage' | 'memory'
const tier = await browserPlatform().storageTier();
if (tier === 'memory') {
  showNotice('Your session will end when you close this tab.');
}

await Koolbase.db.insert('posts', { title: 'Hello', published: true });

const { records, total, isFromCache } = await Koolbase.db.query('posts', {
  filters: { published: true },
  limit: 10,
  orderBy: 'created_at',
  orderDesc: true,
});

const post = records[0];
post.data.title;        // your fields live under .data
post.id, post.collection;

await Koolbase.db.update(post.id, { title: 'Updated' });
await Koolbase.db.delete(post.id);

import { Koolbase, BatchOp } from '@koolbase/js';

const { record, created } = await Koolbase.db.upsert(
  'profiles', { user_id: userId }, { weightKg: 70 },
);

const deleted = await Koolbase.db.deleteWhere('sessions', {
  user_id: userId, status: 'expired',
});

// All of these commit together, or none do.
const results = await Koolbase.db.batch([
  BatchOp.insert('orders', { total: 50, customer_id: customerId }),
  BatchOp.update(inventoryId, { stock: 9 }),
  BatchOp.delete(cartItemId),
]);

const { records, isFromCache } = await Koolbase.db.query('posts', { limit: 20 });

// Queued if offline; sent on reconnect, or force it:
await Koolbase.db.update(id, { title: 'Corrected' });
await Koolbase.db.syncPendingWrites();

// For a sync indicator, and to warn before signing out with unsent work:
const pending = await Koolbase.db.pendingWrites();
if (pending.length) showBadge(pending.length);

const conflicts = await Koolbase.db.conflicts();

for (const c of conflicts) {
  c.local;            // the change the user made
  c.server;           // the record as the server holds it now
  c.divergentFields;  // where they disagree
  c.reason;           // concurrent_modification | baseline_unavailable

  await c.resolveWithLocal();
  // or c.resolveWithServer(), c.resolveWithMerge({ ... }), c.abandon()
}

// Semantic — meaning, not keywords
const result = await Koolbase.db.searchSemantic({
  collection: 'articles',
  field: 'content_embedding',
  queryText: 'how do I move quicker?',
  limit: 10,
});

// Lexical — exact terms, codes, names
await Koolbase.db.searchSemantic({ ..., mode: 'lexical' });

// Hybrid — both, reciprocal rank fusion. Usually the best default.
await Koolbase.db.searchSemantic({ ..., mode: 'hybrid', minSimilarity: 70 });

for (const hit of result.hits) {
  hit.record.data.title;
  hit.distance;
}

const file = input.files[0];

const { object, downloadUrl } = await Koolbase.storage.upload({
  bucket: 'avatars',
  path: `user-${userId}.jpg`,
  file,                   // a File IS a Blob — pass it straight through
});

const url = await Koolbase.storage.getDownloadUrl('avatars', `user-${userId}.jpg`);
await Koolbase.storage.delete('avatars', `user-${userId}.jpg`);

const unsubscribe = Koolbase.realtime.subscribe('messages', (event) => {
  if (event.type === 'deleted') {
    remove(event.recordId);
  } else {
    upsert(event.record!);
  }
});

// Later
unsubscribe();

const result = await Koolbase.functions.invoke('send-welcome-email', {
  userId: '123',
});

if (result.success) console.log(result.data);

if (Koolbase.isEnabled('new_checkout')) showNewFlow();

const timeout = Koolbase.configNumber('timeout_seconds', 30);
const apiUrl  = Koolbase.configString('api_url', 'https://api.myapp.com');
const dark    = Koolbase.configBool('force_dark_mode', false);

const v = Koolbase.checkVersion('1.2.3');
if (v.status === 'force_update') blockAndPrompt();

Koolbase.analytics.track('purchase', { value: 1200, currency: 'GHS' });
Koolbase.analytics.screenView('checkout');
Koolbase.analytics.identify(user.id);
Koolbase.analytics.setUserProperty('plan', 'pro');

Koolbase.analytics.reset();   // on sign-out

import {
  KoolbaseError,
  KoolbaseDataError,
  KoolbaseConflictError,
  KoolbaseUnauthenticatedError,
  KoolbaseOfflineBaselineUnavailableError,
} from '@koolbase/js';

try {
  await Koolbase.db.upsert('users', { email }, { name });
} catch (e) {
  if (e instanceof KoolbaseUnauthenticatedError) {
    goToLogin();                  // already signed out by the time you catch it
  } else if (e instanceof KoolbaseConflictError) {
    showError(`That ${e.field ?? 'value'} is already taken.`);
  } else if (e instanceof KoolbaseDataError) {
    showError(e.message);
  } else {
    throw e;
  }
}