zklighter-perps 1.0.261 → 1.0.263

package/.circleci/config.yml

@@ -30,17 +30,9 @@ jobs:
             sed 's/struct{}/{}/g' server.api > temp.txt && cp temp.txt server.api && rm temp.txt
             goctl api plugin --plugin ./goctl-swagger-amd="swagger -filename openapi.json -host mainnet.zklighter.elliot.ai -schemes https" --api server.api --dir .
 
-      - run:
-          name: openapi.json Post Process
-          command: |
-            cd zklighter-perps/service/apiserver
-            jq 'del(.paths["/api/v1/feedback"], .definitions["ReqSendFeedback"], .paths["/api/v1/ws_status"], .paths["/stream"], .paths["/api/v1/permission"])' openapi.json > temp.json && mv temp.json openapi.json
-            jq 'walk(if type == "object" then with_entries(select(.key != "")) else . end)'  openapi.json > temp.json && mv temp.json openapi.json
-            jq 'walk(if type == "object" and has("summary") then .description = .summary else . end)' openapi.json > temp.json && mv temp.json openapi.json
-            jq 'walk(if type == "object" and has("operationId") then .summary = .operationId else . end)' openapi.json > temp.json && mv temp.json openapi.json
-            jq 'walk(if type == "object" and has("responses") then .responses["400"] = { "description": "Bad request", "schema": { "$ref": "#/definitions/ResultCode" } } else . end)' openapi.json > tmp.json && mv tmp.json openapi.json
-            jq 'walk(if type == "object" and .name == "types" then .type="array" | .items={"type":"integer", "format":"uint8"} | del(.format)  else . end)' openapi.json > tmp.json && mv tmp.json openapi.json
-            sed 's/"-",//g' openapi.json > temp.txt && mv temp.txt openapi.json
+      # NOTE: all openapi.json post-processing now lives in the dedicated
+      # `openapi_postprocess` job (.circleci/openapi_postprocess.py). This job
+      # only generates and persists the raw spec. See README.md.
 
       - store_artifacts:
           path: ~/project/zklighter-perps/service/apiserver/openapi.json
@@ -133,6 +125,23 @@ jobs:
             PR_URL=$(curl -X POST -H "Authorization: Bearer ${GITHUB_TOKEN}" -d '{"title": "'$BE_BRANCH'", "head": "'$BRANCH_NAME'", "base": "main"}' https://api.github.com/repos/elliottech/zklighter-perps-ts/pulls | jq -r '.html_url')
             curl -X POST -H 'Content-type: application/json' --data '{"text":"TypeScript SDK has been updated. Check the PR here: '$PR_URL'", "type": "mrkdwn"}' ${SLACK_URL}
 
+  typecheck:
+    docker:
+      - image: cimg/node:22.4.1
+
+    working_directory: ~/project
+
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: |
+            npm install
+      - run:
+          name: Type-check generated SDK
+          command: |
+            npm run typecheck
+
   update_npm_package:
     docker:
       - image: cimg/node:22.4.1
@@ -186,8 +195,14 @@ workflows:
     when:
       not: << pipeline.parameters.update_ts_sdk >>
     jobs:
+      # Runs on every branch (including the timestamped branches opened by the
+      # update_ts_sdk workflow) so a regenerated SDK that would break consumers
+      # fails its PR check before merge.
+      - typecheck
       - update_npm_package:
           filters:
             branches:
               only: main
+          requires:
+            - typecheck
 

package/.circleci/openapi_postprocess.py

@@ -1,139 +1,283 @@
-import json
+"""Post-process the swagger/openapi.json before the TypeScript SDK is generated.
+
+This is the single source of truth for every transformation applied to the
+spec emitted by goctl-swagger. The raw spec has a number of quirks (empty keys,
+non-standard int16 types, missing error responses, placeholder enum values,
+auto-generated operation ids, etc.) that either break the OpenAPI Generator or
+produce an awkward SDK. See README.md ("OpenAPI post-processing") for the
+rationale behind each step.
+
+Previously some of these fixes lived as inline `jq`/`sed` commands in the
+`update_openapi` CI job. They have been consolidated here so the logic is in one
+place, testable, and easy to reason about.
+
+The steps below run in the same order they used to run in the pipeline:
+the former `jq`/`sed` transforms first, then the original Python transforms.
+"""
 
+import json
 
 FILE = "./openapi.json"
+
+
+def walk(node, fn):
+    """Apply ``fn`` to every node bottom-up, mirroring jq's ``walk``.
+
+    Children are transformed before their parent so ``fn`` always sees
+    already-processed sub-trees, matching the semantics of the jq commands
+    these helpers replaced.
+    """
+    if isinstance(node, dict):
+        node = {key: walk(value, fn) for key, value in node.items()}
+    elif isinstance(node, list):
+        node = [walk(item, fn) for item in node]
+    return fn(node)
+
+
 with open(FILE, "r") as f:
     data = json.load(f)
-    for path in data["paths"]:
-        methods = list(data["paths"][path].keys())
-        has_multiple_methods = len(methods) > 1
-
-        for method in methods:
-            if "api/v1/" in path:
-                base_name = path.split("api/v1/")[1].replace("/", "_")
-                data["paths"][path][method]["summary"] = base_name
-                if has_multiple_methods:
-                    data["paths"][path][method]["operationId"] = f"{base_name}_{method}"
-                else:
-                    data["paths"][path][method]["operationId"] = base_name
-            elif "api/v2/" in path:
-                base_name = path.split("api/v2/")[1].replace("/", "_") + "_v2"
-                data["paths"][path][method]["summary"] = base_name
-                if has_multiple_methods:
-                    data["paths"][path][method]["operationId"] = f"{base_name}_{method}"
-                else:
-                    data["paths"][path][method]["operationId"] = base_name
+
+# ---------------------------------------------------------------------------
+# Step 1. Drop endpoints/definitions that must not be part of the public SDK.
+#   (was: jq 'del(.paths[...], .definitions["ReqSendFeedback"])')
+# ---------------------------------------------------------------------------
+for dropped_path in [
+    "/api/v1/feedback",
+    "/api/v1/ws_status",
+    "/stream",
+    "/api/v1/permission",
+]:
+    data.get("paths", {}).pop(dropped_path, None)
+data.get("definitions", {}).pop("ReqSendFeedback", None)
+
+
+# ---------------------------------------------------------------------------
+# Step 2. Remove empty-string keys emitted by the swagger generator, which the
+#         OpenAPI Generator cannot handle.
+#   (was: jq 'walk(... with_entries(select(.key != "")) ...)')
+# ---------------------------------------------------------------------------
+def _strip_empty_keys(node):
+    if isinstance(node, dict):
+        return {key: value for key, value in node.items() if key != ""}
+    return node
+
+
+data = walk(data, _strip_empty_keys)
+
+
+# ---------------------------------------------------------------------------
+# Step 3. Mirror `summary` into `description` so generated SDK doc comments keep
+#         the original human-readable text before `summary` is overwritten below.
+#   (was: jq 'walk(if has("summary") then .description = .summary end)')
+# ---------------------------------------------------------------------------
+def _summary_to_description(node):
+    if isinstance(node, dict) and "summary" in node:
+        node["description"] = node["summary"]
+    return node
+
+
+data = walk(data, _summary_to_description)
+
+
+# ---------------------------------------------------------------------------
+# Step 4. Seed `summary` from `operationId` (Step 8 may refine it per-path).
+#   (was: jq 'walk(if has("operationId") then .summary = .operationId end)')
+# ---------------------------------------------------------------------------
+def _operation_id_to_summary(node):
+    if isinstance(node, dict) and "operationId" in node:
+        node["summary"] = node["operationId"]
+    return node
+
+
+data = walk(data, _operation_id_to_summary)
+
+
+# ---------------------------------------------------------------------------
+# Step 5. Give every operation a documented 400 response referencing ResultCode.
+#   (was: jq 'walk(if has("responses") then .responses["400"] = {...} end)')
+# ---------------------------------------------------------------------------
+def _add_bad_request_response(node):
+    if isinstance(node, dict) and isinstance(node.get("responses"), dict):
+        node["responses"]["400"] = {
+            "description": "Bad request",
+            "schema": {"$ref": "#/definitions/ResultCode"},
+        }
+    return node
+
+
+data = walk(data, _add_bad_request_response)
+
+
+# ---------------------------------------------------------------------------
+# Step 6. Model the `types` parameter as a byte array (array of uint8) instead of
+#         the non-standard scalar the spec declares.
+#   (was: jq 'walk(if .name == "types" then .type="array" | .items=... | del(.format) end)')
+# ---------------------------------------------------------------------------
+def _types_param_to_byte_array(node):
+    if isinstance(node, dict) and node.get("name") == "types":
+        node["type"] = "array"
+        node["items"] = {"type": "integer", "format": "uint8"}
+        node.pop("format", None)
+    return node
+
+
+data = walk(data, _types_param_to_byte_array)
+
+
+# ---------------------------------------------------------------------------
+# Step 7. Remove placeholder "-" values from enum/array lists.
+#         The former `sed 's/"-",//g'` only stripped a "-" element when it was
+#         followed by another element (i.e. not the last item); we preserve that
+#         behaviour here.
+# ---------------------------------------------------------------------------
+def _drop_dash_values(node):
+    if isinstance(node, list):
+        last_index = len(node) - 1
+        return [
+            value
+            for index, value in enumerate(node)
+            if not (value == "-" and index != last_index)
+        ]
+    return node
+
+
+data = walk(data, _drop_dash_values)
+
+
+# ---------------------------------------------------------------------------
+# Step 8. Derive stable, path-based operationId/summary so generated method
+#         names are predictable (e.g. /api/v1/account -> "account").
+# ---------------------------------------------------------------------------
+for path in data["paths"]:
+    methods = list(data["paths"][path].keys())
+    has_multiple_methods = len(methods) > 1
+
+    for method in methods:
+        if "api/v1/" in path:
+            base_name = path.split("api/v1/")[1].replace("/", "_")
+            data["paths"][path][method]["summary"] = base_name
+            if has_multiple_methods:
+                data["paths"][path][method]["operationId"] = f"{base_name}_{method}"
+            else:
+                data["paths"][path][method]["operationId"] = base_name
+        elif "api/v2/" in path:
+            base_name = path.split("api/v2/")[1].replace("/", "_") + "_v2"
+            data["paths"][path][method]["summary"] = base_name
+            if has_multiple_methods:
+                data["paths"][path][method]["operationId"] = f"{base_name}_{method}"
             else:
-                base_name = path.split("/")[-1]
-                data["paths"][path][method]["summary"] = base_name
-                if has_multiple_methods:
-                    data["paths"][path][method]["operationId"] = f"{base_name}_{method}"
-                else:
-                    data["paths"][path][method]["operationId"] = base_name
-
-            if data["paths"][path][method]["summary"] == "":
-                data["paths"][path][method]["summary"] = "status"
-                if has_multiple_methods:
-                    data["paths"][path][method]["operationId"] = f"status_{method}"
-                else:
-                    data["paths"][path][method]["operationId"] = "status"
-
-    # Replace $ref to int16 types with inline equivalents across all definitions.
-    # int16 and derived map types are not standard OpenAPI and cause the generator
-    # to emit broken model references.
-    def replace_int16_refs(obj):
-        if isinstance(obj, dict):
-            if obj.get("$ref") == "#/definitions/int16":
-                return {"type": "integer", "format": "int64"}
-            if obj.get("$ref") == "#/definitions/mapint16string":
-                return {"type": "object", "additionalProperties": {"type": "string"}}
-            if obj.get("$ref") == "#/definitions/mapstringfloat64":
-                return {"type": "object", "additionalProperties": {"type": "number", "format": "double"}}
-            return {k: replace_int16_refs(v) for k, v in obj.items()}
-        if isinstance(obj, list):
-            return [replace_int16_refs(i) for i in obj]
-        return obj
-
-    for defn_name in list(data["definitions"]):
-        data["definitions"][defn_name] = replace_int16_refs(
-            data["definitions"][defn_name]
-        )
-
-    # Fix enum placement for array types: move enum from array level into items
-    for defn in data["definitions"].values():
-        for prop in defn.get("properties", {}).values():
-            if prop.get("type") == "array" and "enum" in prop:
-                prop["items"]["enum"] = prop.pop("enum")
-
-    # transfer_history type parameter to be array
-    if "/api/v1/transfer/history" in data["paths"]:
-        for method in data["paths"]["/api/v1/transfer/history"].values():
-            for param in method.get("parameters", []):
-                if (
-                    param.get("name") == "type"
-                    and param.get("type") == "string"
-                    and "enum" in param
-                ):
-                    param["type"] = "array"
-                    param["items"] = {"type": "string", "enum": param.pop("enum")}
-                    break
-
-    for path in data["definitions"]:
-        if not path.startswith("Req"):
-            required_fields = list(data["definitions"][path]["properties"].keys())
-            if "message" in required_fields:
-                required_fields.remove("message")
-
-            if "next" in required_fields:
-                required_fields.remove("next")
-
-            if "next_cursor" in required_fields:
-                required_fields.remove("next_cursor")
-
-            if "account_share" in required_fields:
-                required_fields.remove("account_share")
-
-            if "total_funding_paid_out" in required_fields:
-                required_fields.remove("total_funding_paid_out")
-
-            if "pending_unlocks" in required_fields:
-                required_fields.remove("pending_unlocks")
-
-            if "account_trading_mode" in required_fields:
-                required_fields.remove("account_trading_mode")
-
-            if "funding_fee_discounts_enabled" in required_fields:
-                required_fields.remove("funding_fee_discounts_enabled")
-
-            if "hidden" in required_fields:
-                required_fields.remove("hidden")
-
-            if "approved_integrators" in required_fields:
-                required_fields.remove("approved_integrators")
-
-            if "ask_id_str" in required_fields:
-                required_fields.remove("ask_id_str")
-
-            if "bid_id_str" in required_fields:
-                required_fields.remove("bid_id_str")
-
-            if "market_maker_incentive_account_index" in required_fields:
-                required_fields.remove("market_maker_incentive_account_index")
-
-            if "user_tier_last_update" in required_fields:
-                required_fields.remove("user_tier_last_update")
-
-            if path == "Trade":
-                if "taker_fee" in required_fields:
-                    required_fields.remove("taker_fee")
-
-                if "maker_fee" in required_fields:
-                    required_fields.remove("maker_fee")
-
-            if len(required_fields) > 0:
-                data["definitions"][path]["required"] = required_fields
+                data["paths"][path][method]["operationId"] = base_name
+        else:
+            base_name = path.split("/")[-1]
+            data["paths"][path][method]["summary"] = base_name
+            if has_multiple_methods:
+                data["paths"][path][method]["operationId"] = f"{base_name}_{method}"
             else:
-                data["definitions"][path].pop("required", None)
+                data["paths"][path][method]["operationId"] = base_name
+
+        if data["paths"][path][method]["summary"] == "":
+            data["paths"][path][method]["summary"] = "status"
+            if has_multiple_methods:
+                data["paths"][path][method]["operationId"] = f"status_{method}"
+            else:
+                data["paths"][path][method]["operationId"] = "status"
+
+# Replace $ref to int16 types with inline equivalents across all definitions.
+# int16 and derived map types are not standard OpenAPI and cause the generator
+# to emit broken model references.
+def replace_int16_refs(obj):
+    if isinstance(obj, dict):
+        if obj.get("$ref") == "#/definitions/int16":
+            return {"type": "integer", "format": "int64"}
+        if obj.get("$ref") == "#/definitions/mapint16string":
+            return {"type": "object", "additionalProperties": {"type": "string"}}
+        if obj.get("$ref") == "#/definitions/mapstringfloat64":
+            return {"type": "object", "additionalProperties": {"type": "number", "format": "double"}}
+        return {k: replace_int16_refs(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [replace_int16_refs(i) for i in obj]
+    return obj
+
+for defn_name in list(data["definitions"]):
+    data["definitions"][defn_name] = replace_int16_refs(
+        data["definitions"][defn_name]
+    )
+
+# Fix enum placement for array types: move enum from array level into items
+for defn in data["definitions"].values():
+    for prop in defn.get("properties", {}).values():
+        if prop.get("type") == "array" and "enum" in prop:
+            prop["items"]["enum"] = prop.pop("enum")
+
+# transfer_history type parameter to be array
+if "/api/v1/transfer/history" in data["paths"]:
+    for method in data["paths"]["/api/v1/transfer/history"].values():
+        for param in method.get("parameters", []):
+            if (
+                param.get("name") == "type"
+                and param.get("type") == "string"
+                and "enum" in param
+            ):
+                param["type"] = "array"
+                param["items"] = {"type": "string", "enum": param.pop("enum")}
+                break
+
+for path in data["definitions"]:
+    if not path.startswith("Req"):
+        required_fields = list(data["definitions"][path]["properties"].keys())
+        if "message" in required_fields:
+            required_fields.remove("message")
+
+        if "next" in required_fields:
+            required_fields.remove("next")
+
+        if "next_cursor" in required_fields:
+            required_fields.remove("next_cursor")
+
+        if "account_share" in required_fields:
+            required_fields.remove("account_share")
+
+        if "total_funding_paid_out" in required_fields:
+            required_fields.remove("total_funding_paid_out")
+
+        if "pending_unlocks" in required_fields:
+            required_fields.remove("pending_unlocks")
+
+        if "account_trading_mode" in required_fields:
+            required_fields.remove("account_trading_mode")
+
+        if "funding_fee_discounts_enabled" in required_fields:
+            required_fields.remove("funding_fee_discounts_enabled")
+
+        if "hidden" in required_fields:
+            required_fields.remove("hidden")
+
+        if "approved_integrators" in required_fields:
+            required_fields.remove("approved_integrators")
+
+        if "ask_id_str" in required_fields:
+            required_fields.remove("ask_id_str")
+
+        if "bid_id_str" in required_fields:
+            required_fields.remove("bid_id_str")
+
+        if "market_maker_incentive_account_index" in required_fields:
+            required_fields.remove("market_maker_incentive_account_index")
+
+        if "user_tier_last_update" in required_fields:
+            required_fields.remove("user_tier_last_update")
+
+        if path == "Trade":
+            if "taker_fee" in required_fields:
+                required_fields.remove("taker_fee")
+
+            if "maker_fee" in required_fields:
+                required_fields.remove("maker_fee")
+
+        if len(required_fields) > 0:
+            data["definitions"][path]["required"] = required_fields
+        else:
+            data["definitions"][path].pop("required", None)
 
 with open(FILE, "w") as f:
     json.dump(data, f, indent=2)

package/.openapi-generator/FILES

@@ -1,5 +1,6 @@
 apis/AccountApi.ts
 apis/AnnouncementApi.ts
+apis/AtomicordersApi.ts
 apis/BlockApi.ts
 apis/BridgeApi.ts
 apis/CandlestickApi.ts
@@ -39,6 +40,8 @@ models/ApprovedIntegrator.ts
 models/Asset.ts
 models/AssetDetails.ts
 models/AssetStats.ts
+models/AtomicOrder.ts
+models/AtomicOrderLeg.ts
 models/Auth.ts
 models/Block.ts
 models/Blocks.ts
@@ -137,6 +140,7 @@ models/ReqGetAccountTxs.ts
 models/ReqGetAirdropAllocations.ts
 models/ReqGetApiTokens.ts
 models/ReqGetAssetDetails.ts
+models/ReqGetAtomicOrder.ts
 models/ReqGetBlock.ts
 models/ReqGetBlockTxs.ts
 models/ReqGetBridgesByL1Addr.ts
@@ -182,7 +186,10 @@ models/ReqGetTx.ts
 models/ReqGetUserReferrals.ts
 models/ReqGetWithdrawHistory.ts
 models/ReqIsWhitelisted.ts
+models/ReqListAtomicOrders.ts
 models/ReqListRFQs.ts
+models/RespAtomicOrder.ts
+models/RespAtomicOrderList.ts
 models/RespChangeAccountTier.ts
 models/RespCreateRFQ.ts
 models/RespGetApiTokens.ts

package/README.md

@@ -0,0 +1,80 @@
+# zklighter-perps-ts
+
+Auto-generated TypeScript SDK for the Lighter Perps API, published to npm as
+[`zklighter-perps`](https://www.npmjs.com/package/zklighter-perps).
+
+The SDK source (`index.ts`, `runtime.ts`, `apis/`, `models/`) is **generated** by
+the [OpenAPI Generator](https://openapi-generator.tech) from the backend's
+OpenAPI spec. Do not edit the generated files by hand — they are overwritten on
+every regeneration. The package ships raw `.ts` (`"main": "index.ts"`), so
+consumers compile it themselves.
+
+## Generation pipeline (CircleCI)
+
+Defined in [`.circleci/config.yml`](.circleci/config.yml). The `update_ts_sdk`
+workflow (manually triggered) runs three jobs in sequence:
+
+1. **`update_openapi`** — clones `zklighter-perps`, runs `goctl-swagger` to emit
+   the raw `openapi.json`, and persists it. This job no longer transforms the
+   spec; it only generates and persists it.
+2. **`openapi_postprocess`** — runs
+   [`.circleci/openapi_postprocess.py`](.circleci/openapi_postprocess.py), the
+   **single source of truth** for all spec fixups (see below).
+3. **`update_ts_sdk`** — runs the OpenAPI Generator on the post-processed spec,
+   bumps the package version, and opens a PR.
+
+The `update_npm_package` workflow runs on `main`:
+
+- **`typecheck`** — `npm install && npm run typecheck` (`tsc --noEmit` using
+  [`tsconfig.json`](tsconfig.json)). Runs on every branch, including the
+  timestamped branches opened by `update_ts_sdk`, so a regenerated SDK that
+  would fail to compile in a consumer (e.g. `perps-fe`) is caught on its PR.
+- **`update_npm_package`** — publishes to npm (requires `typecheck` to pass).
+
+## OpenAPI post-processing
+
+The spec emitted by `goctl-swagger` has quirks that either break the OpenAPI
+Generator or produce an awkward SDK, so we post-process it before generation.
+All of this lives in **one place** — `.circleci/openapi_postprocess.py`.
+(Historically some of these fixes were inline `jq`/`sed` commands in the
+`update_openapi` job; they have been consolidated into the script so the logic
+is in a single, testable file.)
+
+Why each transform exists:
+
+1. **Drop internal endpoints/definitions** (`/api/v1/feedback`,
+   `/api/v1/ws_status`, `/stream`, `/api/v1/permission`, `ReqSendFeedback`) —
+   not part of the public SDK surface.
+2. **Strip empty-string keys** — the generator emits `""` keys the OpenAPI
+   Generator cannot process.
+3. **Mirror `summary` into `description`** — preserves the original
+   human-readable text as the generated doc comment before `summary` is
+   overwritten in step 8.
+4. **Seed `summary` from `operationId`** — normalizes naming before step 8.
+5. **Add a documented `400` response** referencing `ResultCode` to every
+   operation, so the SDK models the standard error shape.
+6. **Model the `types` parameter as a byte array** (`array` of `uint8`) instead
+   of the non-standard scalar the spec declares.
+7. **Remove placeholder `"-"` enum/array values** that aren't real values.
+8. **Derive stable, path-based `operationId`/`summary`** (e.g.
+   `/api/v1/account` → `account`) so generated method names are predictable.
+9. **Inline non-standard `int16`/map `$ref`s** (`int16`, `mapint16string`,
+   `mapstringfloat64`) — these are not standard OpenAPI and make the generator
+   emit broken model references.
+10. **Move array-level `enum` into `items`** — correct placement for array
+    schemas.
+11. **Make the `transfer/history` `type` param an array** of enum strings.
+12. **Trim over-eager `required` fields** — the backend marks fields required
+    that are actually optional in responses; we relax them so deserialization
+    doesn't reject valid payloads.
+
+## Local development
+
+```bash
+npm install        # installs TypeScript (the only dependency)
+npm run typecheck  # same check CI runs: tsc --noEmit
+```
+
+To test the post-processing script against a spec locally, place an
+`openapi.json` next to the script and run `python3 openapi_postprocess.py`
+(it reads/writes `./openapi.json`).