SDKs

Hooks

Hooks are owner-authored code the generator compiles into a typed seam around a request. They exist for the things a spec can't express: signing a request, injecting a computed header, reshaping a response the API can't change yet.

Hooks are per endpoint and per language. You can't run TypeScript inside a Go SDK, so each language gets its own source.

The two seams

Writing a hook

function beforeRequest(ctx) {
  ctx.headers["X-Request-Time"] = new Date().toISOString();
  return ctx;
}

You author the body; the generator emits the signature and wiring.

Dependencies

A hook that imports a package needs that package declared, or the generated manifest won't install it.

Declare them under Hook packages in your project's SDK settings, per language, e.g. zod@^3 for TypeScript. They're written into the generated package manifest (package.json, pyproject.toml, go.mod, and so on).

Declared per project, not per endpoint

Packages are declared once per language rather than on each endpoint, so a package several endpoints import doesn't produce duplicate manifest entries.

What hooks cost

A hook is code you now maintain, in every language you ship

A hook written for TypeScript does nothing for your Python users. Ten languages means ten implementations of the same idea, each with its own bugs, and none of them visible in your spec.

Before writing one, check whether the same result comes from a spec transform, a pagination or streaming config, or a fix to the spec itself. Those apply to every language at once.

Good reasons to reach for a hook:

Need	Why a hook fits
Request signing (HMAC)	Depends on the body at call time; nothing declarative can express it
A computed header	Value derives from runtime state
Unwrapping a legacy envelope	The API can't change, but callers shouldn't pay for it

Poor reasons:

Need	Do this instead
Adding a static auth header	Set the auth scheme
Renaming a model	A spec transform
Iterating pages	Pagination config
Retrying a failure	Reliability settings

Secrets

A hook is published with the package

Hook source is compiled into the SDK and shipped to npm, PyPI, and the rest. A key hard-coded in a hook is a key published to a public registry. Read secrets from the client's config or the caller's environment.

Where you write them

Select the endpoint in SDK Studio, pick the language, and write the hook body in the editor. It knows the signature and the shape of the context object, so completion works while you type.

Working in GitHub

Open Custom code in SDK Studio and choose the workflow that matches what you want to own.

The workflow chooser appears the first time you open Custom code. Octri remembers your choice for later visits. Select Change workflow when ownership changes.

Edit hooks in GitHub

Choose Edit hooks in GitHub when you want hook files in a repository while Octri continues to own the generated SDK.

Select Connect GitHub.
Under Choose where hook files live, select the repository, branch, folder, and languages.
Select Create hook files.
Edit the marked hook bodies and push them to the watched branch.

Octri watches that branch. Each push reads changed hook files back into the project and starts builds for affected languages. Watching for pushes shows when the connection is healthy. Use Check now after restoring GitHub access or when a webhook was missed.

Missing files or invalid hook markers do not erase existing hooks. The warning appears in Custom code so you can repair the file and push again. Unlink repo removes the connection without deleting repository files.

Own SDK repository

Choose Own SDK repository when your team owns the generated SDK repository.

Select Connect GitHub.
Choose separate staging and production targets.
Select Deploy latest build to staging.
Review the SDK Quality checks in the staging repository.
Select Promote staging to production when that snapshot is ready.

Promotion copies the accepted staging commit, including repository edits kept or resolved during pull request review.

Later generations open a sync pull request. Repository edits outside generated files remain in place. If your team and the next generated SDK changed the same file since the last accepted snapshot, GitHub marks the conflict for review instead of choosing one version. Merge or close the current sync pull request before generating another one.

Spec transforms

Change the spec instead, and every language benefits.

Idempotency

The header a before hook can inspect.