Typed everywhere
Every resource, parameter, and the response envelope
are typed. Twenty-one services — Sites, Environments, Deployments,
Jobs, Webhooks, and the rest — mirror the API’s resource areas.
The official Go SDK gives you a typed, idiomatic client for the
managed.dev API. Its wire types are generated
from the same OpenAPI spec that defines the API —
a CI drift gate regenerates them and fails the build if the SDK and spec ever
disagree — with a curated, hand-written surface on top. The
mf CLI is built on it, so the SDK is exercised by every
CLI release.
TypeScript and PHP SDKs are designed but not yet shipped — see the roadmap below.
The SDK is a thin, typed wrapper over https://api.managed.dev/v1 — not a
second product with its own concepts. Everything you can do with cURL you can
do with the SDK, plus the ergonomics you’d expect from a PaaS client:
Typed everywhere
Every resource, parameter, and the response envelope
are typed. Twenty-one services — Sites, Environments, Deployments,
Jobs, Webhooks, and the rest — mirror the API’s resource areas.
Auto-pagination
Lists return Page[T] — range .Iter(ctx) or call .All(ctx) and
cursor pagination is handled for you, page by
page as you go.
Idempotent retries
The client attaches an Idempotency-Key to
every POST and retries 429/5xx/transport failures with exponential
backoff, honoring Retry-After — a retry replays the original job instead
of creating a second one.
Typed errors
The error envelope surfaces as *forge.Error
carrying Type, Code, Param, RequestID, and DocURL, with
predicates like NotFound() and RateLimited() — match on the code,
don’t parse strings.
Job helpers
Jobs.Wait, WaitSuccess, Stream, and Follow take an
async job to a terminal state — Follow
streams over SSE with a polling fallback, and the Success variants
return a typed *forge.JobError when the job fails.
Pinned version
The client sends Forge-Version: 2026-06-23 — the
API version it was built against — so an
additive API change never silently shifts a payload under you.
It also ships forge.VerifyWebhookSignature for
webhook verification and a forgetest package —
an in-process fake API server for your tests, with self-advancing jobs and
canned errors. Dependencies: the standard library plus google/uuid, nothing
else.
go get terriblegit.com/terrible/forge-goConstruct a client with an API key, then call a
resource. This lists your sites — a sites:read call — iterating every page:
package main
import ( "context" "fmt" "os"
forge "terriblegit.com/terrible/forge-go")
func main() { ctx := context.Background() client := forge.New(os.Getenv("FORGE_TOKEN"))
page, err := client.Sites.List(ctx, nil) if err != nil { if apiErr, ok := forge.AsError(err); ok { fmt.Fprintf(os.Stderr, "api error %s (%s): %s\n", apiErr.Code, apiErr.Type, apiErr.Message) os.Exit(1) } panic(err) }
// Iter fetches each next page lazily as you range. for site, err := range page.Iter(ctx) { if err != nil { panic(err) } fmt.Printf("%s %s %s\n", site.ID, site.Domain, site.Status) }}Most mutations return 202 Accepted and a *forge.Job.
Jobs.FollowSuccess streams progress to a writer and returns a typed
*forge.JobError if the job ends in failed; Jobs.WaitSuccess does the same
without the output stream. This kicks off a build and follows it:
job, err := client.Deployments.CreateBuild(ctx, siteID, envID, forge.BuildCreateParams{ Builder: "wordpress",})if err != nil { return err}
done, err := client.Jobs.FollowSuccess(ctx, job.ID, os.Stdout)if err != nil { var jobErr *forge.JobError if errors.As(err, &jobErr) { return fmt.Errorf("build failed: %s", jobErr.Job.Error.Message) } return err}fmt.Printf("build %s: %s\n", done.ID, done.Status)Job statuses are exactly queued, running, succeeded, and failed;
forge.JobTerminal(job) tells you whether one is done.
Options are functional and composable:
client := forge.New(os.Getenv("FORGE_TOKEN"), forge.WithAPIVersion("2026-06-23"), forge.WithMaxRetries(3), // default 2 forge.WithUserAgent("myapp/1.0"), forge.WithBaseURL("https://api.managed.dev/v1"),)forge.WithoutAutoIdempotency() disables the automatic Idempotency-Key; to
pin a specific key for one request, wrap the context with
forge.WithIdempotencyKey(ctx, key). The default request timeout is 30
seconds (streaming calls have none — cancel via the context), and the client
is safe for concurrent use.
forge.VerifyWebhookSignature checks a
Forge-Signature header — HMAC and timestamp —
in one call:
err := forge.VerifyWebhookSignature(payload, r.Header.Get("Forge-Signature"), os.Getenv("WEBHOOK_SECRET"), forge.DefaultWebhookTolerance)if err != nil { http.Error(w, "bad signature", http.StatusUnauthorized) return}forgetest spins up an in-process fake of the API so your tests don’t need a
network or a key:
srv := forgetest.NewServer(t)srv.Job("job_01J9F2KQ", "running", "succeeded") // self-advances on each poll
job, err := srv.Client.Backups.Create(ctx, "site_01J7QZ3M")done, err := srv.Client.Jobs.WaitSuccess(ctx, job.ID, nil)srv.Data, srv.List, and srv.Error stub canned responses for any route,
and srv.Requests() returns what your code actually sent.
Preview TypeScript and PHP SDKs are designed to come off the same generation pipeline as the Go SDK, with the same shape — auto-pagination, idempotent retries, typed errors, job helpers. They have not shipped; there is no package to install today.