The peqaboo global API

Resolves once the native bridge has handshaked. Always await before calling other APIs.

await peqaboo.ready();
console.log('Bridge ready, version', peqaboo.bridgeVersion);

true when running inside the Peqaboo WebView; false in a plain browser. Use to conditionally fall back.

if (!peqaboo.isInApp) {
  document.body.innerHTML = 'Open in Peqaboo to use this app.';
  return;
}

Host platform reported by the bridge.

if (peqaboo.platform === 'ios') { /* iOS-specific tweak */ }

Native bridge version. v3 supports permission scopes; v2 is legacy.

if (peqaboo.bridgeVersion < 3) {
  alert('Please update Peqaboo to use this BooApp.');
}

BCP-47 language tag of the user (e.g. zh-HK, en-US).

const isChinese = peqaboo.lang.startsWith('zh');

Current logged-in user id, or null if not logged in. Use requireLogin() to force login.

if (!peqaboo.uid) await peqaboo.requireLogin();

Returns the current user. If no user is logged in, opens the native login flow first. Resolves with the User object after success.

scope: auth.requireLogin

const user = await peqaboo.requireLogin();
console.log(user.uid, user.name, user.avatarUrl);

List all pets owned by the current user.

scope: pet.list

const pets = await peqaboo.pet.list();
pets.forEach(p => console.log(p.name, p.species));

Read a single pet by id. Includes full profile, breed, birth date, photo URLs.

scope: pet.read

const pet = await peqaboo.pet.read('pet_abc123');
console.log(pet.weight, pet.allergies);

Update fields on a pet. The user is shown a confirm sheet before any write.

scope: pet.update

await peqaboo.pet.update('pet_abc123', { weight: 5.4 });

Open the native image picker. Set opts.source = 'camera' to skip directly to camera.

scope: media.pickImage

const file = await peqaboo.media.pickImage({ source: 'camera' });
const url = await peqaboo.storage.upload(file);

Pick or capture a video.

scope: media.pickVideo

const video = await peqaboo.media.pickVideo({ maxDuration: 30 });

Open the native camera directly, skipping the chooser.

scope: media.takePhoto

const photo = await peqaboo.media.takePhoto();

Upload a file. Files are scoped to your BooApp and the current user; other apps cannot read them.

scope: storage.upload

const file = await peqaboo.media.pickImage();
const url = await peqaboo.storage.upload(file, { path: 'cards/' });
img.src = url;

Returns one geolocation reading. Triggers a native permission prompt the first time.

scope: location.getCurrent

const { lat, lng } = await peqaboo.location.getCurrent();

Subscribe to position updates. Returns an unsubscribe function.

scope: location.subscribe

const unsub = peqaboo.location.subscribe(coords => {
  console.log(coords.lat, coords.lng);
});
// later
unsub();

Request a payment. The user sees a native modal with full breakdown and must tap Confirm.

scope: payment.request

const r = await peqaboo.payment.request({
  amount: 4800, currency: 'HKD',
  description: 'Loyalty card stamp set'
});
if (r.status === 'success') unlockReward();

Schedule a push for the current user. Useful for reminders, follow-ups, drip flows.

scope: notification.send

await peqaboo.notification.send({
  title: 'Daily walk',
  body: 'Time to walk Mochi!',
  scheduleAt: Date.now() + 8 * 3600 * 1000,
});

Open the native chat sheet. You can prefill a starter message for the user to send.

scope: chat.openWith

await peqaboo.chat.openWith('user_xyz', {
  prefill: 'Hi! I saw your post about the puppy class…'
});

Open the native share sheet.

scope: device.share

await peqaboo.device.share({
  title: 'Mochi got a new card!',
  url: 'https://peqaboo.app/cards/abc',
});

Trigger a haptic tap. Sync — no await needed.

scope: device.haptic

peqaboo.device.haptic('light');

Open the native QR scanner. Resolves with the decoded payload.

scope: device.scanCode

const code = await peqaboo.device.scanCode();
console.log('Scanned:', code);

Set/replace a value. Max 100 KB serialised.

scope: data.write

await peqaboo.data.set('streakCount', 7);

Read a value. Returns null when missing.

scope: data.read

const { value } = await peqaboo.data.get('streakCount');

Delete a key. No-op if absent.

scope: data.write

await peqaboo.data.delete('streakCount');

List keys (latest 500).

scope: data.read

const { keys } = await peqaboo.data.list();

Append with auto-id. Doc cap: 100 KB, 100 top-level fields.

scope: data.write

const visits = peqaboo.collection('visits');
const r = await visits.add({ petId: 'p1', rating: 5 });

Filtered query. If a composite index is missing the call throws QueryNeedsIndexError once — the platform auto-files a deploy ticket; retry in ~5 min.

scope: data.read

const page = await visits.list({
  where: [['petId', '==', 'p1']],
  orderBy: [['_createdAtDate', 'desc']],
  limit: 20,
});

5-second polling fallback (true streaming planned).

scope: data.read

const off = visits.onChange(page => render(page), {
  where: [['petId', '==', 'p1']],
});
// later: off();

Append a public doc visible to every user of your BooApp.

scope: data.shared.write

await peqaboo.shared.collection('leaderboard').add({ score: 99 });

Read shared collection.

scope: data.shared.read

const top = await peqaboo.shared.collection('leaderboard').list({
  orderBy: [['score', 'desc']], limit: 10,
});

Set `installs/{uid}.pinned = true` for this BooApp. The user's public profile then shows it under the Pinned rail.

scope: profile.pin

// After delivering value (e.g. user printed their NFC card),
// prompt them to pin so friends can discover it.
await peqaboo.profile.pinThisApp();

Remove this BooApp from the user’s pinned rail.

scope: profile.pin

await peqaboo.profile.unpinThisApp();

Subscribe to a Bridge Event. Returns an unsubscribe function. Known events: appResume, appPause, authTokenRefreshed, pushReceived, nfcTagDetected, keyboardShow, keyboardHide.

const off = peqaboo.on('appResume', () => {
  refreshData();
});
// later
off();

List the user's friends + recent chat partners. opts.source = 'friends' | 'chat' | 'all' (default 'all').

scope: contacts.read

const { contacts } = await peqaboo.contacts.list({ source: 'friends' });

Show a native bottom-sheet contact picker (Friends / Recent tabs). Resolves with the picked row or null on cancel.

scope: contacts.read

const c = await peqaboo.contacts.pick();
if (c) await peqaboo.chat.openWith(c.uid);

Add a reminder. Body: { petId, title, dueAt (ISO), repeat?, notes? }. Writes to the petReminders collection scoped with sourceBooAppId.

scope: reminder.write

await peqaboo.reminder.add({
  petId: 'p1',
  title: 'Walk Mochi',
  dueAt: new Date(Date.now() + 3600_000).toISOString(),
});

List reminders this BooApp created (others are hidden).

scope: reminder.write

const { reminders } = await peqaboo.reminder.list();

Delete a reminder. Only succeeds if the reminder was created by this BooApp.

scope: reminder.write

await peqaboo.reminder.delete(r.reminderId);

Add a pet record. Body: { petId, type, occurredAt (ISO), notes?, attachments? }. Writes to petRecords with sourceBooAppId.

scope: record.write

await peqaboo.record.add({
  petId: 'p1',
  type: 'vaccine',
  occurredAt: new Date().toISOString(),
  notes: 'Annual rabies booster',
});

Schedule a push. Body: { when (ISO, future), title, body, link?, imageUrl?, actions? }.

scope: notification.schedule

await peqaboo.notification.schedule({
  when: new Date(Date.now() + 8 * 3600_000).toISOString(),
  title: 'Daily walk',
  body: 'Time to walk Mochi!',
});

Search products. Returns up to 30 hits.

scope: market.read

const { hits } = await peqaboo.market.search('cat food');

Read a single product detail.

scope: market.read

const detail = await peqaboo.market.get(hits[0].productId);