JavaScript SDK: functions

aura.functions is a FunctionsService. You almost never build it yourself.

import { createClient } from '@aurabase/aurabase-js'

const aura = createClient('https://my-app.aurabase.cloud', 'aura_anon_…')
aura.functions.invoke('hello')

The package @aurabase/functions is installed with @aurabase/aurabase-js. Install it alone only if you compose your own client from @aurabase/core. It requires Node.js 20 or later and ships ES modules and CommonJS with type declarations.

Every method returns Promise<AuraResponse<T>>, an object { data, error } that never throws:

Test data rather than error when you need the value: only then does TypeScript know it is not null.

invoke<T = unknown>(
  name: string,
  options?: {
    body?: unknown
    method?: string
    path?: string
    headers?: Record<string, string>
    signal?: AbortSignal
    timeout?: number
    responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer'
  },
): Promise<AuraResponse<T>>

name is encoded in the URL, so a value containing /, ? or # cannot leave its position. A name that contains such characters simply is not found.

invoke refreshes an expired user session first, sends the user's JWT when there is one, and never retries a call.

How to use it: Invoke a function. How it fails: Errors, timeouts and retries.

list(): Promise<AuraResponse<FunctionDef[]>>
get(nameOrId: string): Promise<AuraResponse<FunctionDef>>

Both need a service_role key. get accepts the name or the id; if a function is named like an id, the name wins. A FunctionDef contains the source code and the variables of the function, which is why a public key receives 403.

There is no method to deploy, update or delete a function, or to write secrets: use the HTTP API or the CLI.

enqueueJob(
  functionName: string,
  options?: { payload?: unknown; delaySecs?: number; maxAttempts?: number },
): Promise<AuraResponse<Job>>

listJobs(options?: { status?: string; limit?: number }): Promise<AuraResponse<Job[]>>
getJob(jobId: string): Promise<AuraResponse<Job>>

• enqueueJob returns { code: 'bad_request', status: 400 } without any request when functionName is empty or only spaces, and trims the name otherwise.
• listJobs filters on status (pending, running, completed, failed, dead) and returns between 1 and 500 jobs, 50 by default.
• Retrying dead jobs has no method: see the dead-letter queue.

listCronJobs(): Promise<AuraResponse<CronJob[]>>
createCronJob(
  name: string,
  schedule: string,
  functionName: string,
  options?: { payload?: unknown },
): Promise<AuraResponse<CronJob>>
deleteCronJob(name: string): Promise<AuraResponse<null>>

schedule has 5 or 6 fields, in UTC. deleteCronJob takes the name, and returns 404 for an unknown name. There is no getCronJob or updateCronJob.

Exported by @aurabase/aurabase-js and @aurabase/functions:

import {
  FunctionsHttpError,
  FunctionsRelayError,
  isRelayStatus,
  type FunctionsResponseType,
} from '@aurabase/aurabase-js'

Both error classes extend AuraError, so isAuraError(error) is true. AuraError has status, code, message, details, retryAfter, and the getters isNotFound, isUnauthorized, isForbidden and isRateLimited.

Data types, exported by @aurabase/aurabase-js: