$tasks

Internal Use Only

The $tasks SDK provides an abstraction for managing cloud tasks via a backend microservice. These tasks are scheduled HTTP requests that will be executed at a specified time (with a tolerance of +/- 5 minutes). This SDK is designed for internal use by Hexlabs services.

This can be used client side because of auto secret injection. The nuxt module inject a proxy server route into the app. The SDK the sends a request to the proxy, the proxy attaches an auth header and sends off the request.

Overview

Tasks are queued with metadata about the request, its scheduling, and retry behavior. They are executed by a dedicated microservice when their scheduled time arrives.

Task Type

export type QueueTask = {
    request: {
        url: string
        headers?: Record<string, string>
        params?: Record<string, string | number | boolean>
        body?: any
        method: "get" | "post" | "put" | "delete" | "patch" | "head" | "options"
    }
    retries?: number
    performAt: number // Unix timestamp in milliseconds
    status: "pending" | "completed" | "failed"
}

API Methods

create(task: QueueTask)

Schedules a new task to be executed.

await $tasks.create({
    request: {
        url: "https://example.com/webhook",
        method: "post",
        body: { some: "payload" },
    },
    performAt: Date.now() + 600_000, // In 10 minutes
    status: "pending",
})

update(id: string, data: Partial<QueueTask>)

Updates an existing scheduled task by ID.

await $tasks.update("abc123", {
    retries: 5,
})

read(id: string)

Fetches the current state of a scheduled task by ID.

const task = await $tasks.read("abc123")

delete(id: string)

Deletes a scheduled task by ID. Useful for canceling.

await $tasks.delete("abc123")

Notes

• Tasks are executed approximately at performAt ± 5 minutes.
• Failed tasks may be retried depending on the retries field.
• The API assumes the backend service is available at /api/hexlabs.
• All interactions are POST-based and routed through the service=tasks namespace.

Example Use Case

$tasks.create({
    request: {
        url: "https://webhook.site/custom",
        method: "post",
        body: { event: "triggered" },
    },
    performAt: Date.now() + 1000 * 60 * 15, // 15 minutes from now
    status: "pending",
})

Good to Know

• $tasks enables deferred execution of logic, which is ideal for time-delayed workflows like email scheduling, webhooks, and retries.
• Since it wraps $fetch, it respects all Nuxt runtime environment rules.

Limitations

• Not intended for public or client-side use.
• Backend must have permission to access the microservice.
• No built-in authentication (assumed trusted environment).

Future Ideas

• Add retry strategies (exponential backoff, etc.)
• Status polling for UI dashboards
• Dependency chaining for sequential tasks