annyong

@liquidweb-dev/annyong — typed HTTP request SDKs for two APIs maintained by Liquid Web:

• Liquid Web API (https://api.liquidweb.com) — supports HTTP basic auth or bearer tokens. Liquid Web publishes a bespoke docs format at /docs/json rather than OpenAPI.
• Nocworx API — already publishes an OpenAPI spec.

The two SDKs are kept architecturally separate: there is no merged top-level surface, only sub-path imports.

Install (consumer)

npm install @liquidweb-dev/annyong

import { accountAuthToken } from '@liquidweb-dev/annyong/lw';
import { someNocworxOperation } from '@liquidweb-dev/annyong/nocworx';

Liquid Web API: x-force-compliant-http-status-codes

For the Liquid Web SDK only: some failures are returned as HTTP 200 with an error body unless the client asks otherwise. Sending x-force-compliant-http-status-codes: 1 makes the API use conventional HTTP status codes, which lines up with response.ok, throwOnError, and TanStack Query treating failures as errors.

Highly recommended: set it once on the shared client from @liquidweb-dev/annyong/lw (together with any auth headers you already use):

import { client } from '@liquidweb-dev/annyong/lw';

client.setConfig({
  headers: {
    'x-force-compliant-http-status-codes': '1',
  },
});

TanStack Query (optional peer)

The package exposes generated hooks for TanStack Query v5 and v4 as separate subpaths (peer @tanstack/react-query is ^4.0.0 || ^5.0.0, optional):

// v5 (@tanstack/react-query@5)
import { accountDetailsOptions } from '@liquidweb-dev/annyong/lw/react-query';

// v4 (@tanstack/react-query@4)
import { accountDetailsOptions } from '@liquidweb-dev/annyong/lw/react-query-v4';

Nocworx mirrors the same …/react-query and …/react-query-v4 entries. Hey API emits v5-style @tanstack/react-query.gen.ts; openapi-ts.config.ts output.postProcess runs packages/react-query-v4-codegen to write @tanstack/react-query-v4.gen.ts next to it.

How it's built

LW bespoke docs JSON  ─►  convert-liquidweb-openapi.ts  ─►  liquidweb-openapi.json ─┐
                                                                                     ├─►  @hey-api/openapi-ts  ─►  lw/  + nocworx/  ─►  tsc  ─►  dist/
Nocworx OpenAPI spec  ─────────────────────────────────────► nocworx-openapi.json ──┘

1. Liquid Web → OpenAPI. convert-liquidweb-openapi.ts fetches https://api.liquidweb.com/docs/json and converts LW's bespoke types to OpenAPI 3.0.3 (liquidweb-openapi.json). Nocworx skips this step.
2. OpenAPI → SDK. @hey-api/openapi-ts (configured in openapi-ts.config.ts) generates the typed SDK into lw/ and nocworx/, including @tanstack/react-query.gen.ts. Each job’s postProcess step then emits @tanstack/react-query-v4.gen.ts from that file.
3. SDK → publishable package. tsc -p tsconfig.build.json emits .js + .d.ts to dist/. A postbuild script merges package-dist.json overrides into dist/package.json and copies README.md.

Dev commands

Requires Node ≥ 22.13.0 (enforced by @hey-api/openapi-ts's engines).

| Command | What it does | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | npm install | Install dependencies | | npm run generateLwOpenApi | Regenerate liquidweb-openapi.json from LW's docs | | npm run openapi-ts | Regenerate lw/ and nocworx/ SDKs from the OpenAPI specs | | npm run dumpPatchedNocworxSpec | Write nocworx-openapi.patched.json — upstream spec with nocworx-spec-overrides applied (for upstream handoff diffs) | | npm run auditNocworxOverrides | List overrides.ts entries that are no-ops against current nocworx-openapi.json | | npm run compareNocworxSdkExports | Diff baseline vs current nocworx/gen export names → scripts/nocworx-sdk-export-diff.json (gitignored; use when authoring breaking-change migration guides) | | npm run build | prebuild (clear dist/) + tsc emit + postbuild (write dist/package.json + copy README) | | npm run yalc | Build, then publish dist/ to the local yalc store for local-linking into consumer repos | | npm run docs:dev | Start the docs site (Astro) at http://localhost:3000 | | npm run docs:build | Build the static docs site to docs/dist/ | | npm run docs:preview | Serve the built docs at http://localhost:3000 |

npm run generateLwOpenApi accepts flags after --:

npm run generateLwOpenApi -- --version <bleed|v1|...>   # default: bleed
npm run generateLwOpenApi -- --out ./liquidweb-openapi.json

If LW adds new bespoke types the converter doesn't recognize, the script logs them at the end of the run. Add real schemas to COMPONENTS (with constraints) or to STRING_TYPES (intentional plain-string fallback) in convert-liquidweb-openapi.ts.

Nocworx spec overrides

nocworx-openapi.json is kept byte-identical to upstream. At codegen, packages/nocworx-spec-overrides applies an in-memory overlay via parser.patch.input (withNocworxOverrides):

1. Deep-merge src/overrides.ts — typed partial OpenAPI (paths, components.schemas); only keys you change
2. Global errors — apply-global-errors.ts adds error_response bodies on 4xx/5xx

Merge rules (src/merge.ts, deepmerge): $ref objects replace the target node (never merge into { type: "object" } stubs); null in the overlay removes a key (e.g. "_input": null or stripping example).

npm run dumpPatchedNocworxSpec writes nocworx-openapi.patched.json (gitignored) with the same structural overrides as codegen. Diff it against nocworx-openapi.json when coordinating upstream fixes. It intentionally omits annyong-only operation patches (such as endpoint-doc JSDoc) that are not Nocworx spec changes.

Bumping upstream nocworx-openapi.json: replace the file → prune overrides.ts → npm run openapi-ts → npm run compareNocworxSdkExports. Migration guides document breaking changes only (renamed/removed SDK exports). Add docs/migrations/nocworx-openapi-v<N>.md and bump annyong major when the compare script shows those; not for type-only upstream improvements. See packages/nocworx-spec-overrides/UPSTREAM-BUMP.md.

Consumer guides: docs/migrations/ (docs site Migrations, npm run docs:dev → /migrations/).

Publish

The repo's root package.json is private: true. Publishing happens from dist/:

npm run build
cd dist
npm publish

dist/package.json is generated at build time from the merge of root package.json + package-dist.json, with scripts and devDependencies stripped.

Local linking with yalc

To dogfood unpublished changes from a consumer repo, use yalc (npm i -g yalc if you don't have it):

# From this repo
npm run yalc

# From the consumer repo
yalc add @liquidweb-dev/annyong

npm run yalc is npm run build && cd dist && yalc push --private && cd .. — it runs the same build pipeline as publishing and pushes dist/ (not the root) so consumers resolve the same sub-path exports (/lw, /nocworx, /lw/react-query, etc.) they'd get from npm. The --private flag tells yalc to ignore the root private: true field.

Docs site

docs/ is a static Astro site that documents the SDK. It generates a page per operation (~1135), per named type alias (~414), and a per-operation playground that hits the API live via the SDK's client.

Source of truth for the docs is the generated SDK code itself (lw/gen/sdk.gen.ts + lw/gen/types.gen.ts), parsed at build time via the TypeScript Compiler API. Operations come from sdk.gen.ts (function name → method + URL); request/response shapes come from the type aliases in types.gen.ts walked into a uniform Node tree. JSDoc descriptions are preserved.

Build output is fully static (docs/dist/) — host on any CDN. Dev/preview server binds to port 3000 (so the LW dev API's CORS allowlist accepts it).

Stack

Node + TypeScript + Astro (docs site). Generator: @hey-api/openapi-ts.