@alpacacloud/js

@alpacacloud/js

The official JavaScript/TypeScript client for Alpaca Cloud.

Install

npm install @alpacacloud/js
# or
yarn add @alpacacloud/js
# or
pnpm add @alpacacloud/js

Quick Start

import { createClient } from '@alpacacloud/js'

const alp = createClient(
  'https://your-project.alpaca-cloud.com',
  'your-anon-key'
)

Database

// Fetch rows
const { data, error } = await alp
  .from('posts')
  .select('id, title, author(name)')
  .eq('published', true)
  .order('created_at', { ascending: false })
  .limit(10)

// Insert
const { data } = await alp
  .from('posts')
  .insert({ title: 'Hello World', published: false })

// Update
await alp.from('posts').update({ published: true }).eq('id', 123)

// Delete
await alp.from('posts').delete().eq('id', 123)

// Single row
const { data: post } = await alp
  .from('posts')
  .select('*')
  .eq('id', 1)
  .single()

// Count
const { count } = await alp
  .from('posts')
  .select('*', { count: 'exact' })
  .eq('published', true)
  .count()

Auth

// Sign up
const { data, error } = await alp.auth.signUp({
  email: '[e-mail]',
  password: 'supersecret',
})

// Sign in
const { data, error } = await alp.auth.signInWithPassword({
  email: '[e-mail]',
  password: 'supersecret',
})

// OAuth (Google, GitHub, Discord...)
await alp.auth.signInWithOAuth({ provider: 'github' })

// Magic link
await alp.auth.signInWithOTP({ email: '[e-mail]' })

// Get current user
const { data: { user } } = await alp.auth.getUser()

// Listen for auth changes
alp.auth.onAuthStateChange((event, session) => {
  console.log(event, session?.user?.email)
})

// Sign out
await alp.auth.signOut()

Storage

// Upload a file
const { data, error } = await alp
  .storage
  .from('avatars')
  .upload('user-123.png', file, { contentType: 'image/png' })

// Get a public URL
const { data: { publicUrl } } = alp
  .storage
  .from('avatars')
  .getPublicUrl('user-123.png')

// Download
const { data: blob } = await alp.storage.from('avatars').download('user-123.png')

// List files
const { data: files } = await alp.storage.from('avatars').list('users/')

// Delete
await alp.storage.from('avatars').remove(['user-123.png'])

// Signed URL (private files)
const { data: { signedUrl } } = await alp
  .storage.from('private').createSignedUrl('report.pdf', 60) // 60 seconds

// Create a bucket
await alp.storage.createBucket('avatars', { public: true })

Realtime

// Subscribe to database changes
const channel = alp
  .realtime
  .channel('db-changes')
  .on('postgres_changes', { schema: 'public', table: 'messages', eventType: '*' }, (payload) => {
    console.log('Change:', payload.eventType, payload.new)
  })
  .subscribe()

// Broadcast (pub/sub between clients)
const room = alp.realtime.channel('room:general')

room.on('broadcast', { event: 'cursor' }, (msg) => {
  console.log('Cursor moved:', msg.payload)
})
room.subscribe()

room.send({ type: 'broadcast', event: 'cursor', payload: { x: 100, y: 200 } })

// Presence (who's online)
room.on('presence', { event: 'sync' }, ({ currentPresences }) => {
  console.log('Online users:', currentPresences)
})
room.track({ userId: 'abc', name: 'Mel' })

// Cleanup
await alp.realtime.removeChannel(channel)

SQL over HTTP (edge driver)

Run parameterised SQL over HTTPS — works in edge runtimes (Cloudflare Workers, Vercel Edge, Deno) and inside Functions/Sandboxes, no TCP needed. RLS is enforced by your token's role.

// single query
const { data, error } = await alp.sql('select * from posts where id = $1', [postId])
console.log(data.rows)

// atomic batch (one transaction)
const { data } = await alp.sql([
  { query: 'insert into logs(msg) values ($1)', params: ['hi'] },
  { query: 'select count(*) from logs' },
])
console.log(data.results)

Sandboxes

Ephemeral, isolated environments to run code (E2B / Fly-Machines style). Sandboxes are account-scoped, so point the client at the platform API with apiUrl:

const alp = createClient(PROJECT_URL, ANON_KEY, {
  apiUrl: 'https://api.alpaca-cloud.com',
})

// One-shot: run a snippet and get the result
const { data } = await alp.sandboxes.runCode({ language: 'python', code: 'print(2**10)' })
console.log(data.stdout) // "1024\n"

// Or manage a session: create → exec / files → kill
const { data: { handle } } = await alp.sandboxes.create({ template: 'python' })
await handle.writeFile('data.txt', 'hello')
const res = await handle.exec({ cmd: 'cat data.txt && python --version' })
console.log(res.data.stdout)
await handle.kill()

TypeScript

Fully typed. Pass your row type as a generic:

interface Post { id: number; title: string; published: boolean }

const { data } = await alp.from<Post>('posts').select('*')
// data is Post[] | null

Made with 🦙 by the Alpaca Cloud team.