@vibeli/sdk

Neutral data / auth / realtime / functions / integrations client for Vibeli apps — one core for the browser (SPA) and Deno/Edge functions. Talks the Vibeli gateway wire contract; never leaks the backend (no Appwrite shapes in types, errors, or export names).

Install

npm install @vibeli/sdk

socket.io-client is a dependency (loaded lazily on the first realtime subscription); zod is an optional peer (used by codegen-emitted schemas).

Entry points

| Import | Use | |---|---| | @vibeli/sdk | Browser client: createClient, createMockClient, runConformance, types | | @vibeli/sdk/functions | Server side (Deno/Edge): createClientFromRequest | | @vibeli/sdk/errors | VibeliError taxonomy (also re-exported from the two above) |

Browser

import { createClient } from '@vibeli/sdk'

const vibeli = createClient({ appId, gatewayUrl, contractVersion })

const page = await vibeli.entities.Order.list({ sort: [{ field: 'created_date', dir: 'desc' }] })
const order = await vibeli.entities.Order.create({ total: 100 })   // server fields are excluded by type
const off = vibeli.entities.Order.subscribe((e) => { /* e: ChangeEvent<Order> */ })

await vibeli.auth.me()                 // throws VibeliError{code:'unauthenticated'} if no session
vibeli.auth.login(returnUrl)           // redirect to the Vibeli-hosted login page (no password through the SDK)
const out = await vibeli.functions.invoke('myFn', payload)
await vibeli.integrations.Core.UploadFile({ file })
vibeli.cleanup()                       // close the realtime socket on unmount

Deno/Edge function

import { createClientFromRequest } from 'npm:@vibeli/[email protected]/functions'

Deno.serve(async (req) => {
  const vibeli = createClientFromRequest(req)
  const user = await vibeli.auth.me()                  // User | null (anonymous is valid)
  const rows = await vibeli.entities.Order.filter({ status: { eq: 'open' } })   // caller-scoped
  const all = await vibeli.asServiceRole.entities.Order.list()                  // full access
  return Response.json({ ok: true })                   // business "no" is 2xx + body, never a non-2xx
})

Errors

import { VibeliError } from '@vibeli/sdk'
try { await vibeli.entities.Order.get(id) }
catch (e) { if (e instanceof VibeliError && e.code === 'not_found') { /* … */ } }

Codes: unauthenticated | forbidden | not_found | bad_request | validation | capability_unavailable | rate_limited | function_failed | timeout | internal.

Testing

createMockClient(seed?) is an in-memory VibeliClient; runConformance(client) is the contract suite that runs against both the mock and a live gateway.