Esc

↑↓ move↵ openIndex · Pagefind
SDKs and tools

Call the API from typed code.

TypeScript and Python clients for every implemented REST operation, with pagination, idempotency keys, safe retries and webhook signature checks. The same operations are available as one OpenAPI 3.0 document and a Postman collection.

OpenAPI + Postman: downloadSDKs: not yet on npm or PyPI2,549 operations

OpenAPI document and Postman collection

openapi.json is every implemented operation in one OpenAPI 3.0 document, generated from the same module contracts as the REST reference. Each operation has a readable operationId, and the x-os-paginated and x-os-idempotent extensions mark list endpoints and writes that accept an Idempotency-Key. Use it with your own code generator, or import it into Insomnia, Bruno or Postman.

os-construction.postman_collection.json is a Postman v2.1 collection with one folder per tool. Import it, then set the collection variables token, companyId and projectId; baseUrl defaults to https://app.os.construction. Writes send Idempotency-Key: {{$guid}}.

Both files are regenerated from the app's contracts whenever the API changes.

TypeScript and Python SDKs

Status: the packages @os-construction/sdk (npm) and os-construction (PyPI) are built and tested, but not published yet. Until they are, the names below will not install from the public registries; the examples show the API they will have. If you need an SDK build before then, contact us.

  • Every implemented operation
    2,549 REST operations generated from the app's API contracts. Only operations the API serves are included, so nothing in the client returns 404 by design.
  • Typed
    TypeScript: path, query, body and response types per operation. Python: one method per operation with typed path parameters, TypedDict models for named schemas, and a py.typed marker; checked with mypy --strict.
  • Pagination
    paginate() walks every page through the Link next relation; request() returns Total, Per-Page and the links.
  • Idempotency keys
    Pass idempotencyKey / idempotency_key, or turn on automatic keys for writes. Retries reuse the same key, and the response says when it was replayed.
  • Retries that cannot double a write
    Network errors, 409, 429 and 502-504 are retried with Retry-After, but only for GET requests and writes that carry a key.
  • Webhook verification
    Checks X-OS-Signature (HMAC-SHA256 of the raw body) in constant time, supports a list of secrets for rotation, and is tested against vectors produced by the server signer.

Operation names

Names come from the method and path, so you can derive them from the REST reference. Versions other than v1.0 carry a suffix.

  • listProjectRfis
    list_project_rfis
    GET /rest/v1.0/projects/{project_id}/rfis
  • getProjectRfi
    get_project_rfi
    GET /rest/v1.0/projects/{project_id}/rfis/{id}
  • createProjectRfi
    create_project_rfi
    POST /rest/v1.0/projects/{project_id}/rfis
  • advanceBallInCourtProjectRfi
    advance_ball_in_court_project_rfi
    PATCH …/rfis/{id}/advance_ball_in_court
  • listProjectSubmittalsV11
    list_project_submittals_v11
    GET /rest/v1.1/projects/{project_id}/submittals
Quickstart
import { OsConstructionClient } from "@os-construction/sdk";

const client = new OsConstructionClient({
  token: process.env.OS_ACCESS_TOKEN,
  companyId: 1,              // sent as OS-Company-Id
  autoIdempotencyKey: true,  // every write gets a fresh Idempotency-Key
  retries: 2,                // GETs and keyed writes only
});

// One page, typed path, query and response
const open = await client.call("listProjectRfis", {
  path: { project_id: 2 },
  query: { "filters[status]": "open", per_page: 50 },
});

// Every page: follows the Link "next" relation
for await (const rfi of client.paginate("listProjectRfis", { path: { project_id: 2 } })) {
  console.log(rfi.number, rfi.subject);
}

// Same call as a method
const rfi = await client.ops.getProjectRfi({ path: { project_id: 2, id: 17 } });

Verify webhooks

Each delivery carries X-OS-Signature: sha256=<hex>, an HMAC-SHA256 of the raw body with your subscription's signing secret. Verify the raw bytes before parsing JSON, then de-duplicate on X-OS-Event-ID. See Webhooks for the event catalog and retry schedule.

Receive an event
import { constructWebhookEvent, WebhookVerificationError } from "@os-construction/sdk";

// Express: app.post("/hooks/os", express.raw({ type: "application/json" }), handler)
export async function handler(req, res) {
  try {
    const { event, eventId, body } = await constructWebhookEvent({
      payload: req.body,           // the raw bytes, before JSON parsing
      headers: req.headers,
      secret: process.env.OS_WEBHOOK_SECRET, // [old, new] while rotating
    });
    // de-duplicate on eventId, then handle event
    res.sendStatus(204);
  } catch (e) {
    if (e instanceof WebhookVerificationError) return res.sendStatus(401);
    throw e;
  }
}

Building from source

For teams with access to the os.construction repository: both SDKs live under tools/ with build and verify scripts. The TypeScript package has no runtime dependencies (it uses the runtime's fetch and Web Crypto) and runs on Node.js 18+, Deno, Bun and modern browsers. The Python package needs Python 3.10+ and httpx.

Build and verifyshell
# From a checkout of the os.construction repository
npm --prefix app ci
npm --prefix tools/sdk-ts run verify     # build, tests, pack, install, typed consumer check
npm --prefix tools/sdk-ts pack           # os-construction-sdk-0.1.0.tgz

cd tools/sdk-python
python -m venv .venv && .venv/Scripts/python -m pip install httpx pytest build hatchling mypy
.venv/Scripts/python scripts/verify.py   # tests, mypy --strict, wheel, fresh-venv install
.venv/Scripts/python -m build            # dist/os_construction-0.1.0-py3-none-any.whl

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file