JavaScript: install and configure

#Install

npm install @sovaria/sdk

#Create a client

import { createClient } from '@sovaria/sdk'

export const sovaria = createClient(
  import.meta.env.VITE_SOVARIA_URL,        // https://<project-ref>.sovarias.in
  import.meta.env.VITE_SOVARIA_ANON_KEY,
)

One client per app (or per request on a server acting for users). The URL names the project, so no ids are needed. Which key goes where: Connect your app; variable names: Environment variables.

#Options

Retry and transport settings are set when you construct the client directly: new SovariaSDK({ baseUrl, accessToken, refreshToken, persistSession, fetchImpl, retryCount, retryBaseDelayMs }).

#Retries and idempotency

• Requests that fail with 429, 500, 502, 503 or 504, or with a network error, are retried — 4 attempts in all by default (retryCount), with jittered exponential backoff from 100 ms (retryBaseDelayMs, at most 10 s). After a 429 the SDK waits at least the Retry-After time.
• Writes (POST, PUT, PATCH, DELETE) are retried too, and a retried write is applied once: every write carries one Idempotency-Key from its first attempt, so if the server applied it but the response was lost, the retry gets the stored answer instead of running it again. A retry that arrives while the first try is still running waits for it.
• The key belongs to one call. To make a write safe for your own code to repeat (after a crash or a page reload, say), pass a key you can recreate, such as order-<id>: sovaria.request(method, path, { body, idempotencyKey }). The server keeps the answer for an hour (two minutes when it carries tokens or keys); the same key with a different body gets 409 IDEMPOTENCY_PAYLOAD_MISMATCH. idempotent: true is no longer needed and is still accepted.
• Access tokens are refreshed a minute before they expire, and once more after a 401; you don't need to handle expiry yourself.

#Errors

Failed calls throw SovariaError with a stable code to branch on and a message you can show to users:

import { SovariaError } from '@sovaria/sdk'

try {
  await sovaria.data.sql('insert into orders (total) values ($1)', [42])
} catch (err) {
  if (!(err instanceof SovariaError)) throw err
  switch (err.code) {
    case 'UNAUTHENTICATED': return goToSignIn()
    case 'PERMISSION_DENIED': return toast('You can\'t do that.')
    case 'PLAN_LIMIT_REACHED':
    case 'PLAN_QUOTA_EXHAUSTED': return showUpgrade(err.detail)
    case 'RATE_LIMITED': return toast('Too many requests — try again in a moment.')
    default: console.error(err.technicalMessage); toast(err.message)
  }
}

#Troubleshooting