SDKs & Client Libraries

Production-ready SDKs with full type safety, automatic retries, circuit breakers, and gRPC support. Node.js, Go, and Python include streaming helpers; PHP exposes unary gRPC today.

Node.js

Production Ready

TypeScript-first with ESM/CommonJS support

Python

Production Ready

Full type hints with Pydantic models

Production Ready

Idiomatic Go with full type safety

PHP

Production Ready

PHP 8.2+ with readonly DTOs

Installation

npm install @spooled/sdk

SDK	Package	Published (2026-07-15)
Node.js	`@spooled/sdk`	1.0.39
Python	`spooled`	1.0.23
Go	`spooled-sdk-go`	v1.0.21
PHP	`spooled-cloud/spooled`	v1.0.20

Install commands above resolve the latest published version. Pin explicitly in production when you need a known good release.

Quick Start

Create a job with any SDK (or cURL):

curl -X POST https://api.spooled.cloud/api/v1/jobs \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queue_name": "my-queue",
    "payload": {
      "event": "user.created",
      "user_id": "usr_123",
      "email": "alice@example.com"
    },
    "idempotency_key": "user-created-usr_123"
  }'

import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

const userId = 'usr_123';

// Create a job
const { id } = await client.jobs.create({
  queueName: 'email-notifications',
  payload: {
    to: 'user@example.com',
    subject: 'Welcome!',
    template: 'welcome',
  },
  idempotencyKey: `welcome-${userId}`,
  maxRetries: 5,
});

console.log(`Created job: ${id}`);

from spooled import SpooledClient
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

image_id = "img_123"

# Create a background job
result = client.jobs.create({
    "queue_name": "image-processing",
    "payload": {
        "image_url": "https://example.com/image.jpg",
        "operations": ["resize", "compress"],
        "output_format": "webp"
    },
    "idempotency_key": f"process-image-{image_id}",
    "max_retries": 3
})

print(f"Created job: {result.id}")

client.close()

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

func ptr[T any](v T) *T { return &v }

func main() {
	client, err := spooled.NewClient(spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")))
	if err != nil {
		panic(err)
	}

	resp, err := client.Jobs().Create(context.Background(), &resources.CreateJobRequest{
		QueueName:      "my-queue",
		Payload:        map[string]any{"key": "value"},
		IdempotencyKey: ptr("unique-key"),
		MaxRetries:     ptr(3),
	})
	if err != nil {
		panic(err)
	}

	fmt.Printf("Created job: %s\n", resp.ID)
}

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

$userId = 'usr_123';

// Create a job
$job = $client->jobs->create([
    'queue' => 'email-notifications',
    'payload' => [
        'to' => 'user@example.com',
        'subject' => 'Welcome!',
        'template' => 'welcome',
    ],
    'idempotencyKey' => "welcome-{$userId}",
    'maxRetries' => 5,
]);

echo "Created job: {$job->id}\n";

Node.js / TypeScript SDK

Production ready

The Node.js SDK is fully featured and ready for production use. Includes comprehensive test coverage and type-safe APIs.

Features

Full TypeScript Support - Comprehensive type definitions
ESM & CommonJS - Works in any Node.js project
Automatic Retries - Exponential backoff with jitter
Circuit Breaker - Fault tolerance built-in
gRPC Streaming - High-performance workers (lower latency than HTTP)
Worker Runtime - Built-in job processing
Workflow DAGs - Complex job dependencies
Realtime Events - WebSocket & SSE support
Plan Limits - Automatic enforcement

Core Resources

Jobs

Create, list, claim, complete, fail, retry, cancel

Workers

Queues

List, get, stats, pause, resume, delete, configure

Schedules

Cron schedules with timezone support

Workflows

DAG execution with job dependencies

DLQ

Dead letter queue operations

gRPC Client

High-performance gRPC client. Hosted API quotas are enforced server-side and surfaced as typed/structured errors:

import { SpooledGrpcClient } from '@spooled/sdk';

const grpcClient = new SpooledGrpcClient({
  address: 'grpc.spooled.cloud:443',
  apiKey: process.env.SPOOLED_API_KEY!,
  useTls: true,
});

await grpcClient.waitForReady();

// Register worker
const { workerId } = await grpcClient.workers.register({
  queueName: 'emails',
  hostname: 'worker-1',
  maxConcurrency: 10,
});

// Dequeue jobs in batch
const { jobs } = await grpcClient.queue.dequeue({
  queueName: 'emails',
  workerId,
  batchSize: 10,
});

// Process and complete (echo leaseId for lease fencing)
for (const job of jobs) {
  await processJob(job);
  await grpcClient.queue.complete({
    jobId: job.id,
    workerId,
    leaseId: job.leaseId ?? undefined,
    result: { success: true },
  });
}

grpcClient.close();

Performance: gRPC is typically lower-latency than HTTP for high-throughput workers

Documentation

Python SDK

Production ready

The Python SDK is fully featured, type-safe, and ready for production use. Includes sync & async clients, worker runtime, gRPC support, and comprehensive error handling.

Features

Full Type Safety - Pydantic models with type hints
Sync & Async - Both synchronous and asynchronous clients
Worker Runtime - Decorator-based job processing
gRPC Support - High-performance gRPC client (optional)
Real-time Events - WebSocket and SSE support
Resilience - Retry logic with exponential backoff and circuit breaker
Production Ready - Comprehensive error handling and logging

Documentation

Go SDK

Production ready

The Go SDK is fully featured, idiomatic, and ready for production use. Includes comprehensive test coverage, type-safe APIs, gRPC support, and worker runtime.

Features

Idiomatic Go - Functional options pattern, context propagation
Full Type Safety - Strongly typed request/response structures
gRPC Support - High-performance gRPC client for workers
Worker Runtime - Built-in concurrent job processing
Automatic Retries - Exponential backoff with jitter
Circuit Breaker - Fault tolerance built-in
Real-time Events - WebSocket & SSE support
Workflows - DAG execution with job dependencies

Quick Start

curl -X POST https://api.spooled.cloud/api/v1/jobs \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queue_name": "my-queue",
    "payload": {
      "event": "user.created",
      "user_id": "usr_123",
      "email": "alice@example.com"
    },
    "idempotency_key": "user-created-usr_123"
  }'

import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

const userId = 'usr_123';

// Create a job
const { id } = await client.jobs.create({
  queueName: 'email-notifications',
  payload: {
    to: 'user@example.com',
    subject: 'Welcome!',
    template: 'welcome',
  },
  idempotencyKey: `welcome-${userId}`,
  maxRetries: 5,
});

console.log(`Created job: ${id}`);

from spooled import SpooledClient
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

image_id = "img_123"

# Create a background job
result = client.jobs.create({
    "queue_name": "image-processing",
    "payload": {
        "image_url": "https://example.com/image.jpg",
        "operations": ["resize", "compress"],
        "output_format": "webp"
    },
    "idempotency_key": f"process-image-{image_id}",
    "max_retries": 3
})

print(f"Created job: {result.id}")

client.close()

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

func ptr[T any](v T) *T { return &v }

func main() {
	client, err := spooled.NewClient(spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")))
	if err != nil {
		panic(err)
	}

	resp, err := client.Jobs().Create(context.Background(), &resources.CreateJobRequest{
		QueueName:      "my-queue",
		Payload:        map[string]any{"key": "value"},
		IdempotencyKey: ptr("unique-key"),
		MaxRetries:     ptr(3),
	})
	if err != nil {
		panic(err)
	}

	fmt.Printf("Created job: %s\n", resp.ID)
}

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

$userId = 'usr_123';

// Create a job
$job = $client->jobs->create([
    'queue' => 'email-notifications',
    'payload' => [
        'to' => 'user@example.com',
        'subject' => 'Welcome!',
        'template' => 'welcome',
    ],
    'idempotencyKey' => "welcome-{$userId}",
    'maxRetries' => 5,
]);

echo "Created job: {$job->id}\n";

Documentation

PHP SDK

Production ready

The PHP SDK is fully featured, type-safe, and ready for production use. Requires PHP 8.2+ with full readonly DTO support, worker runtime, optional gRPC, and comprehensive error handling.

Features

PHP 8.2+ - Modern PHP with readonly properties and type hints
PSR-Compliant - Works with any PSR-compatible HTTP client and logger
Worker Runtime - Built-in job processing with concurrency control
gRPC Support - Optional high-performance unary gRPC client (no public StreamJobs / ProcessJobs wrappers yet — use Node, Go, or Python for streaming helpers)
Real-time Events - WebSocket and SSE support
Resilience - Retry logic with exponential backoff and circuit breaker
Framework Agnostic - Works with Laravel, Symfony, or vanilla PHP
Webhook Ingestion - Validate GitHub, Stripe, and custom webhooks

Quick Start

curl -X POST https://api.spooled.cloud/api/v1/jobs \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queue_name": "my-queue",
    "payload": {
      "event": "user.created",
      "user_id": "usr_123",
      "email": "alice@example.com"
    },
    "idempotency_key": "user-created-usr_123"
  }'

import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

const userId = 'usr_123';

// Create a job
const { id } = await client.jobs.create({
  queueName: 'email-notifications',
  payload: {
    to: 'user@example.com',
    subject: 'Welcome!',
    template: 'welcome',
  },
  idempotencyKey: `welcome-${userId}`,
  maxRetries: 5,
});

console.log(`Created job: ${id}`);

from spooled import SpooledClient
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

image_id = "img_123"

# Create a background job
result = client.jobs.create({
    "queue_name": "image-processing",
    "payload": {
        "image_url": "https://example.com/image.jpg",
        "operations": ["resize", "compress"],
        "output_format": "webp"
    },
    "idempotency_key": f"process-image-{image_id}",
    "max_retries": 3
})

print(f"Created job: {result.id}")

client.close()

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

func ptr[T any](v T) *T { return &v }

func main() {
	client, err := spooled.NewClient(spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")))
	if err != nil {
		panic(err)
	}

	resp, err := client.Jobs().Create(context.Background(), &resources.CreateJobRequest{
		QueueName:      "my-queue",
		Payload:        map[string]any{"key": "value"},
		IdempotencyKey: ptr("unique-key"),
		MaxRetries:     ptr(3),
	})
	if err != nil {
		panic(err)
	}

	fmt.Printf("Created job: %s\n", resp.ID)
}

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

$userId = 'usr_123';

// Create a job
$job = $client->jobs->create([
    'queue' => 'email-notifications',
    'payload' => [
        'to' => 'user@example.com',
        'subject' => 'Welcome!',
        'template' => 'welcome',
    ],
    'idempotencyKey' => "welcome-{$userId}",
    'maxRetries' => 5,
]);

echo "Created job: {$job->id}\n";

Documentation

Plan Limits

The hosted API enforces tier-based quotas (SDKs surface the same 429 / quota errors). Numbers match Limits and backend plans.rs:

Tier	Active Jobs	Daily Jobs	Queues	Workers
Free	10	1,000	2	1
Starter	500	10,000	10	5
Pro	5,000	100,000	50	25
Enterprise	Unlimited	Unlimited	Unlimited	Unlimited

See the Limits documentation for the full matrix (API keys, schedules, workflows, payload size, rate limits, retention).

Dashboard Tip

Account → Usage

What to look for:

→ Current usage vs plan limits
→ Jobs created today
→ Active workers and queues

Actions:

Upgrade plan if approaching limits
Monitor usage trends

SDKs & Client Libraries

Installation

Quick Start

Node.js / TypeScript SDK

Production ready

Features

Core Resources

Jobs

Workers

Queues

Schedules

Workflows

DLQ

gRPC Client

Documentation

Python SDK

Production ready

Features

Documentation

Go SDK

Production ready

Features

Quick Start

Documentation

PHP SDK

Production ready

Features

Quick Start

Documentation

Plan Limits

Dashboard Tip

Need help?