superhuman-docs-sdk

README

Superhuman Docs SDK

SDKs generated from the Smithy model for the Superhuman Docs API v1.

The source API description is the public OpenAPI document at https://docs.superhuman.com/apis/v1/openapi.json. The published document still identifies itself as Coda API v1 and lists https://coda.io/apis/v1 as the default server, so the generated clients use that base URL by default while the Smithy namespace is com.superhuman.docs.v1.

SDKs

Language	Package	Notes
Go	github.com/its-felix/superhuman-docs-sdk/go	The Go module is rooted at this repository so normal vX.Y.Z tags work.
Python	superhuman-docs	Built by the release workflow.
Rust	superhuman-docs	Typed client and model crate under rust.
Zig	superhuman-docs module	Consumed through Zig's package manager from this git repository.

Generated API shape

Each language exposes one client for the service. Direct RPC-style operations, currently Whoami and ResolveBrowserLink, are methods on that client. API operations owned by Smithy resources are grouped under resource clients, with stable lifecycle names such as Create, Read, Update, Delete, and List (using the language's normal naming convention). Child resources are reachable from their parent; for example, row listing is exposed through the equivalent of client.Tables().Rows().List(options).

Inputs and outputs are generated from the Smithy model as strict native types. Smithy enums are native enums in Python, Rust, and Zig, and typed string constants in Go. In particular, ColumnFormatType is generated this way in all four SDKs.

Every operation crosses one public, customizable request-transport boundary. Go, Python, and Zig provide standard-library defaults; Rust accepts an injected transport because its standard library does not include an HTTP client.

Install

Go:

go get github.com/its-felix/superhuman-docs-sdk/go@v0.4.1

Python:

python -m pip install superhuman-docs

Zig:

zig fetch --save git+https://github.com/its-felix/superhuman-docs-sdk.git

Then add the module in your build.zig:

const docs_dep = b.dependency("superhuman_docs", .{
    .target = target,
    .optimize = optimize,
});

exe.root_module.addImport("superhuman-docs", docs_dep.module("superhuman-docs"));

Rust:

superhuman-docs = { git = "https://github.com/its-felix/superhuman-docs-sdk.git", package = "superhuman-docs" }

Layout

• smithy/model: shared Smithy model
• smithy/scripts/openapi_to_smithy.py: OpenAPI-to-Smithy generator
• smithy/generator: Maven-based Smithy-Build SDK generator plugins
• docs: generated Markdown service and resource reference
• go: generated Go package
• python: generated Python package
• rust: generated Rust client and model crate
• zig: generated Zig source package
• .github/workflows/ci.yml: validation and generated-source freshness checks
• .github/workflows/release.yml: tag-driven release publishing

Regeneration

After changing smithy/model, regenerate the SDKs:

./build.sh

The script builds and installs the Smithy generator, runs smithy build, copies generated artifacts from smithy/build/smithy/source/.../sdk into docs/ and the package directories, and runs the SDK tests for tools available on PATH. To generate only one target, pass markdown, python, go, rust, or zig:

./build.sh python

CI uses Java 17, Maven, and the Smithy CLI for generation.

git diff --exit-code -- docs go python rust zig build.zig build.zig.zon

The CI workflow runs the generators and fails if generated files differ from the committed tree.

Releases

Push a semver tag like v1.2.3 to publish:

• Go: the release workflow primes proxy.golang.org for github.com/its-felix/superhuman-docs-sdk@v1.2.3; users import the package at github.com/its-felix/superhuman-docs-sdk/go.
• Python: the workflow builds the package artifact. The tag version must match python/pyproject.toml.
• Rust: the workflow verifies the crate builds from the repository workspace. The tag version must match rust/Cargo.toml.
• Zig: there is no central Zig package registry to upload to. The workflow verifies the tag is buildable and fetchable as a Zig package from the git repository. The tag version must match build.zig.zon.