Quickstart

This guide starts with an empty file. First, you fetch public data. Then, you make calls that require a signed-in user. You do not have to understand each type or option.

1. Import the SDK and create a client

import { PackbaseSDK } from '@packbase/sdk-ts'

const pb = new PackbaseSDK()
     
const pb: PackbaseSDK

PackbaseSDK is the class that the library supplies. new PackbaseSDK() creates one client. In this guide, pb is the client variable. Call methods on pb to communicate with Packbase.

Create one client and use it in all parts of your application. Do not create a client for each request.

Without an API key, this client can read public endpoints. In a browser, it can also use the current user's Packbase session cookie. Step 3 gives more information about authentication.

2. Fetch a public profile

const profile = await pb.profiles('rek')
       
const profile: Profile

console.log(profile.id)
console.log(profile.display_name)
console.log(profile.about?.bio)

pb.profiles('rek') gets the profile with the username rek. Use await because the request is asynchronous. Your function must be async unless your environment supports top-level await.

The result is a Profile object. The ?. operator in profile.about?.bio supports profiles that do not have an about section.

3. Make an authenticated request

Some data is private to the current user. For example, pb.me() requests the profile of the signed-in user:

const me = await pb.me()
     
const me: Profile

console.log(me.username)

Replace 'your-api-key' with an API key or Clerk JWT. Do not put a secret key in source code that you commit. Load the key from an environment variable. In a browser application, you can omit apiKey if the user is signed in to Packbase. The browser sends the session cookie.

The Authentication guide gives more information about both methods.

4. List packs

A pack is a Packbase community. The list response contains a packs array and information about the list.

const result = await pb.packs.list()
       
const result: PackList

for (const pack of result.packs) {
  console.log(pack.display_name)
}

To fetch one known pack, pass its real UUID:

const pack = await pb.packs('00000000-0000-0000-0000-000000000000')
console.log(pack.display_name)

The all-zero UUID shows the required format. It does not identify a pack.

5. Create a howl

Packbase calls posts “howls.” To create a howl, supply authentication, a pack ID, content, and one rating tag.

const howl = await pb.howls.create({
  tenant_id: 'your-pack-uuid',
  body: 'Hello, Packbase! 🐾',
  tags: ['rating_safe'],
})

console.log('Howl created:', howl.id)

Replace the placeholder values before running this. The signed-in user also needs permission to post in that pack.

The server creates a howl in a background job. The SDK checks the job and waits for the completed howl. Thus, the code requires only one await. Read the Howls guide for uploads, progress updates, and manual polling.

6. Catch request errors

Requests can fail because of an incorrect ID, an expired key, or a server error. Put calls that can fail in a try/catch block:

try {
  const profile = await pb.profiles('rek')
  console.log(profile.display_name)
} catch (error) {
  if (error instanceof PackbaseError) {
    console.error(`Packbase returned ${error.status}: ${error.summary}`)
  } else {
    console.error('The request could not reach Packbase', error)
  }
}

You can now use the SDK. The reference pages list each method. The guides explain the applicable workflows.

Next steps