Async Job Polling

Some operations take more time than an API request. Howl creation can process images, video, or other uploaded files. Thus, Packbase starts a background job and immediately gives the SDK a job ID. The work continues on the server.

The SDK then polls the job every second. Polling continues until the job is complete, the job fails, or the wait times out. By default, pb.howls.create() controls this loop. Use the options in this guide for progress updates or different timing.

How it works

pb.howls.create(data)
  → POST /howl/create        (enqueues job, returns { id })
  → GET /howl/create/status/:id   (polls every 1 s)
  → GET /howl/create/status/:id   (polls every 1 s)
  → ...
  → GET /howl/:id            (job done; fetch the finished Howl)
  → returns Howl

The SDK asks Packbase to create the howl. Packbase starts a job and returns { id }.
The SDK checks the job's status once per interval until it is 'completed' or 'failed'.
When the job is complete, the SDK fetches the finished howl and returns it to your code.

The route names in the diagram are internal HTTP requests. Do not call them directly.

Default behavior

// Polls every 1 second, times out after 30 seconds
const  = await ..({
  : 'pack-uuid',
  : 'Hello!',
  : ['rating_safe'],
})

The application receives one promise. await resumes with a completed Howl.

Customizing polling options

Pass a second options object to create() to override the defaults. The unit for values that end in Ms is milliseconds. Thus, 500 is 0.5 seconds and 120_000 is 2 minutes:

const  = await ..(
  {
    : 'pack-uuid',
    : null,
    : ['rating_safe'],
    : ['asset-uuid'],
  },
  {
    : 500,    // poll every 500 ms (default: 1000)
    : 120_000, // give up after 2 minutes (default: 30000)
  },
)

`PollOptions` reference

Option	Type	Default	Description
`intervalMs`	`number`	`1000`	Milliseconds between each status check.
`timeoutMs`	`number`	`30000`	Maximum total wait time before throwing a timeout error.
`onProgress`	`(status: HowlJobStatus) => void`	Not set	Callback called after each status poll.

Tracking progress

onProgress is a callback that the SDK calls after each status check. Use it to update a progress bar or show status text:

const  = await ..(
  {
    : 'pack-uuid',
    : null,
    : ['rating_safe'],
    : ['asset-1', 'asset-2', 'asset-3'],
  },
  {
    : ({ status,  }: HowlJobStatus) => {                    
status: "pending" | "uploading" | "converting" | "processing" | "completed" | "failed"
      .(
        `Job ${}: ${.}/${.} assets`,
      )
    },
  },
)

TypeScript describes the callback value as HowlJobStatus. Its status field can be any of the following string values:

import type { HowlJobStatus } from '@packbase/sdk-ts'

type _Status = HowlJobStatus['status']      
type _Status = "pending" | "uploading" | "converting" | "processing" | "completed" | "failed"

Opting out of automatic polling

Pass { poll: false } to prevent the SDK from waiting. The call returns an object that contains the job ID. It does not return a completed howl:

const  = await ..(
  { : 'pack-uuid', : 'hi', : ['rating_safe'] },
  { : false },
)

// job.id is the UUID of the howl once complete
// Store this ID somewhere if you plan to check the job later.
.(`Howl will be at: https://packbase.app/howl/${.}`)

Handling timeout errors

If the total wait exceeds timeoutMs, the SDK stops polling and throws a PackbaseError with status 408:

try {
  const  = await ..(
    { : 'pack-uuid', : 'Hello', : ['rating_safe'] },
    { : 10_000 }, // tight deadline
  )
} catch () {
  if ( instanceof  && . === 408) {
    .('Howl is still processing. Check back later using the job ID.')
  }
}

A timeout means that the client stopped the wait. The background job can continue. Do not submit the same howl again until you make sure that this action cannot create a duplicate.

Handling failed jobs

If the server says the job itself failed, the SDK throws a PackbaseError with status 500:

try {
  const  = await ..({
    : 'pack-uuid', : 'hi', : ['rating_safe'],
  })
} catch () {
  if ( instanceof  && .) {
    .('Howl creation failed:', .)
  }
}

Job ID equals Howl ID

The job ID is also the UUID of the completed howl. You can save the howl ID before processing is complete. An application can use this ID to show a pending item immediately. Make sure that the interface identifies the item as not ready.

const  = await ..(
  { : 'pack-uuid', : 'hi', : ['rating_safe'] },
  { : false },
)

// Link to the howl before it is ready.
.(`https://packbase.app/howl/${.}`)

// Fetch the howl after the job is complete.
const  = await .(.)

Async Job Polling

On this page