Howls

A howl is a post on Packbase. Every howl belongs to a pack, which is a Packbase community. A howl can contain text, sanitized HTML, uploaded media, or a mix of those.

This guide starts with text howls. It then explains rating tags, uploads, and background processing.

Fetching a single howl

const howl = await pb.howls('howl-uuid')

console.log(howl.id)
console.log(howl.body)
console.log(howl.user.username)
console.log(howl.reactions)

Replace 'howl-uuid' with a howl ID. pb.howls('howl-uuid') creates a HowlHandle. It does not make a request until you await it. The result is a Howl object. This object contains the post, its author, and related data from the endpoint.

Creating a howl

A howl can require media processing. Thus, Packbase does the work in a background job. By default, pb.howls.create() starts the job and checks its status. The method returns when the completed howl is available.

const howl = await pb.howls.create({
  tenant_id: 'your-pack-uuid',  // required: the pack to post in
  body: '<p>Hello from the SDK! 🐾</p>',
  tags: ['rating_safe'],        // must include exactly one rating tag
})

console.log(howl.id) // the finished Howl

tenant_id is the ID of the pack receiving the howl (the server calls pack IDs “tenant IDs” in this request). The current user must be allowed to post there.

Required fields

TypeScript shows missing fields in your editor. The table describes each field:

Rating tags

Each howl requires exactly one rating tag. Clients use this tag to present the content. The rating tag can occur at any position in the tags array:

// Safe howl with additional tags
const tags1: [string, ...string[]] = ['art', 'digital', 'rating_safe']

// Mature howl
const tags2: [string, ...string[]] = ['rating_mature', 'gore']

Attaching uploaded assets

Use pb.howls.upload to initialize an asset, append one or more binary segments, finalize it, and inspect its status. Upload response bodies are currently JsonObject because the server has not published stable response schemas.

await pb.howls.upload.init({ totalBytes: file.size, assetType: file.type })
await pb.howls.upload.append({
  assetId,
  segmentIndex: 0,
  asset: file,
  fileName: 'upload.bin',
})
await pb.howls.upload.finalize(assetId)
const status = await pb.howls.upload.status(assetId)

The SDK supplies the protocol commands. It sends appended assets as multipart FormData. After finalization, pass the returned asset IDs to howl creation:

const howl = await pb.howls.create({
  tenant_id: 'pack-uuid',
  body: null,
  tags: ['rating_safe'],
  asset_ids: ['asset-uuid-1', 'asset-uuid-2'],
})

Tracking creation progress

Pass an onProgress callback when your interface needs to show what the background job is doing:

const howl = await pb.howls.create(
  {
    tenant_id: 'pack-uuid',
    body: null,
    tags: ['rating_safe'],
    asset_ids: ['asset-uuid'],
  },
  {
    onProgress: (status: HowlJobStatus) => {
      const { currentAsset, totalAssets } = status.progress
      console.log(`Processing asset ${currentAsset} / ${totalAssets}`)
    },
  },
)

Manual polling

To store the pending job and check it later, pass { poll: false }. The method immediately returns the job ID. It does not wait for a completed Howl:

const job = await pb.howls.create(
  { tenant_id: 'pack-uuid', body: 'hi', tags: ['rating_safe'] },
  { poll: false },
)

// job.id === the howl's future UUID
// Poll GET /howl/create/status/:id manually (or use a Poller directly)
console.log('Job started:', job.id)

Deleting a howl

await pb.howls('howl-id').delete()

Reacting

// Add a reaction
await pb.howls('howl-id').react('🔥')

// Remove your reactions from the howl
await pb.howls('howl-id').unreact()

If you add the same reaction two times, the server returns a 400 error. react() adds a reaction. It does not toggle a reaction. Call unreact() to remove the current user's reactions.

Commenting

const { id: commentId } = await pb.howls('howl-id').comment('Great post!')

Rehowling (repost)

const { id: rehowlId } = await pb.howls('howl-id').rehowl()

Reporting a howl

ReportReason contains the report categories that the API accepts. The optional second argument is a note for moderators. Use it to give information that is not in the category.

// Report with a reason
await pb.howls('howl-id').report(ReportReason.Spam)

// Report with a reason and additional notes
await pb.howls('howl-id').report(ReportReason.Misinformation, 'Link to source material.')

Available reasons:

Content types

Packbase can return howling_alongside and howling_echo in response data. You cannot use them to create a howl with this method. Pass text, or omit content_type. If you omit it, the SDK supplies text.