Everyframe · TypeScript SDK reference
Running jobs
The SDK builds the pipeline (g.json() + g.io()); you wrap it in a JobMessage and a transport runs it. Primary integration: publish over your tenant AMQP connection to the Everyframe platform. Connections are provisioned per tenant and usage is metered on the platform side. The hosted HTTP API via @renderbox/client is the alternative when you'd rather not hold an AMQP connection.
@jtdigital/renderbox-sdk on npm →Submitting a graph
graph_ir: g.json() · input_files: g.io().inputsThe SDK produces the pipeline; you assemble the job. g.json() is the graph_ir and g.io() returns the S3-to-sandbox bindings ({ inputs: InputFile[], outputs }). Identity (job id, tenant, user) comes from YOUR app and auth, not the SDK. Combine them into a JobMessage and publish to the renderbox exchange yourself (scaffolded projects: the renderbox module's submit()).
| Param | Type | Description |
|---|---|---|
| graph_ir required | GraphJSON | g.json(): the compiled pipeline. |
| input_files required | InputFile[] | g.io().inputs: { s3_key, filename, content_type }, derived from your open() keys. |
| job_id required | string | Your app's id for the job, echoed on every progress/completion message. |
| tenant_id required | string | Your tenant id: routes results to your queues and meters usage. |
| bindings | Bindings | Slot bindings for parameterized (slot-based) graphs. |
The wire contract
import type { JobMessage, ProgressMessage, CompletionMessage, InputFile, OutputSpec } from '@jtdigital/renderbox-sdk'The typed contract between your service and the platform. You publish JobMessage to the renderbox exchange; ProgressMessage and CompletionMessage arrive on your results.<tenant>.progress and results.<tenant>.completed queues. On success, CompletionMessage.outputs[].s3_key points at the rendered file in the shared bucket.
Tenant AMQP connection
AMQP: renderbox exchange in, results.<tenant>.* outWe provision per-tenant credentials for the platform broker; usage is monitored and metered per tenant on the platform side. Scaffolded projects get the transport half ready-made (the renderbox module: S3 put, submit, onProgress/onCompleted consumers); plain Node projects pair the SDK with amqplib and @aws-sdk/client-s3.
new Renderbox(options)
new Renderbox({ apiKey?: string, baseUrl?: string, timeoutMs?: number })Create a hosted-API client. Reads RENDERBOX_API_KEY and RENDERBOX_BASE_URL from the environment when omitted. All requests carry Authorization: Bearer <key>, retry transient failures (429/5xx) with exponential backoff honouring Retry-After, and support AbortSignal timeouts.
rb.assets.upload
rb.assets.upload(data: Blob | Uint8Array, opts: { filename: string; contentType: string }): Promise<Asset>Upload source footage via a presigned URL. The returned asset id is what you bind to a graph's input slots on submission.
rb.run
rb.run(graph: Graph, opts: RunOpts): Promise<Job>Submit a graph and wait for the terminal state in one call: create + wait. Accepts inputs (slot to asset-id bindings), outputFormat, webhookUrl, ttlSeconds, and an onProgress callback.
| Param | Type | Description |
|---|---|---|
| inputs required | Record<string, string> | Maps graph input names to uploaded asset ids. |
| outputFormat | string | Output container, e.g. 'mp4'. |
| onProgress | (job: Job) => void | Called on every poll with fresh progress. |
| webhookUrl | string | POSTed job events instead of polling. |
| ttlSeconds | number | How long results stay downloadable. |
rb.jobs.create / get / cancel
rb.jobs.create(graph, opts): Promise<Job>The unbundled lifecycle: create submits the graph JSON to POST /v1/jobs, get fetches current state, cancel stops a queued or running job.
rb.jobs.wait
rb.jobs.wait(id: string, opts?: { timeoutMs?: number; onProgress?: (job: Job) => void }): Promise<Job>Poll until the job reaches a terminal state (completed | failed | cancelled), honouring the server's poll_after_ms hint. job.progress carries percent (0-100, or null when it can't be computed), frame, fps and speed.
rb.jobs.stream
rb.jobs.stream(id: string): AsyncGenerator<SSEEvent>Server-sent events as an async generator (for await (const event of rb.jobs.stream(id))) instead of polling.
rb.jobs.list / listAll
rb.jobs.list(opts?: { limit?: number; after?: string }): Promise<Page<Job>>Paginated job history; listAll is an async generator over every page.
Job result
job.output: { download_url, asset_id, format, duration_seconds, resolution }A completed job exposes the rendered output's download URL and metadata. Failures throw a typed error: BadRequestError, AuthenticationError, QuotaExceededError, NotFoundError, RateLimitError, InternalServerError, or ConnectionError.