feat!: replace the openapi-ts client with protobuf-es + connect-gateway-es

.github/workflows/ci.yaml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - release
+      - v1
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: 'pnpm'
+      - name: Install
+        run: pnpm install
+      - name: Build
+        run: pnpm build
+      - name: Test
+        run: pnpm test

.github/workflows/publish.yaml

@@ -16,12 +16,10 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
           ref: ${{ github.event.inputs.commit }}
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 9
+      - uses: pnpm/action-setup@v6
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           cache: 'pnpm'
           registry-url: 'https://registry.npmjs.org'
       - name: Set NPM variables
@@ -41,7 +39,7 @@ jobs:
         id: semantic
         uses: cycjimmy/semantic-release-action@v4
         with:
-          semantic_version: 24.0.0
+          semantic_version: 25.0.5
         env:
           GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}
       - name: Release Summary

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) and other coding
+agents when working with this repository.
+
+## What this repository is
+
+`@sentio/api` — the TypeScript client for the [Sentio](https://sentio.xyz)
+public API, published to npm. The bindings are generated from Sentio's
+protobuf definitions with [protobuf-es](https://github.com/bufbuild/protobuf-es)
+and call the REST API through [connect-es](https://github.com/connectrpc/connect-es)
+using the [@sentio/connect-gateway-es](https://github.com/sentioxyz/connect-gateway-es)
+transport (the grpc-gateway REST dialect, routed by the `google.api.http`
+option bytes embedded in the generated descriptors).
+
+## Generated vs hand-written
+
+| Path | Owner |
+|---|---|
+| `src/gen/**` | **CI-owned — never hand-edit.** Synced by Sentio's internal CI from the proto sources, generated with visibility-filtered codegen (public REST surface only: methods need a `google.api.http` binding and public visibility; everything else, including unreachable types, is pruned at the descriptor level). Local edits will be overwritten by the next sync. |
+| `openapi.json`, `doc/` | CI-owned — the OpenAPI spec and HTML reference for the same surface. |
+| `src/client.ts`, `src/index.ts`, `test/`, configs | Hand-written; edit here. |
+
+API surface changes (new endpoints, fields, visibility) happen upstream in
+Sentio's proto definitions, not in this repository.
+
+## Commands
+
+```bash
+pnpm install        # also builds via the prepare script
+pnpm build          # tsc -> dist/
+pnpm test           # node:test via tsx; offline tests always run,
+                    # the live test runs only when SENTIO_API_KEY is set
+```
+
+The package is ESM-only and requires Node 24+. pnpm 11 needs the build-script
+approval in `pnpm-workspace.yaml` (`allowBuilds: esbuild`).
+
+## Architecture notes
+
+- `createSentioTransport({ apiKey, baseUrl, ... })` builds a connect Transport
+  speaking the gateway REST dialect; `apiKey` is sent as the `api-key` header.
+  `createSentioClient(Service, options)` is the one-service shortcut; for
+  several services create one transport and use connect's `createClient`.
+- Default `baseUrl` is `https://app.sentio.xyz`, which serves the annotation
+  paths (`/api/v1/...`) verbatim. `https://api.sentio.xyz` serves the same API
+  under `/v1/...` (the prefix-stripped form used in the REST docs and
+  `openapi.json`) and will NOT route the annotation paths — don't point the
+  transport at it.
+- protobuf-es conventions apply: request messages are partial init shapes
+  (omitted fields take proto defaults), `oneof` fields are `{ case, value }`
+  discriminated unions, errors are connect-es `ConnectError`s carrying the
+  server's `google.rpc.Status` details.
+- `src/index.ts` re-exports the service descriptors only. Do NOT add blanket
+  `export *` of generated modules — request/response type names repeat across
+  services and would collide. Message types are deep-imported by consumers via
+  the `@sentio/api/gen/*` subpath.
+
+## Releases
+
+semantic-release with conventional commits (angular preset + custom rules in
+`release.config.mjs`): pushes to `main` publish `rc` prereleases, the
+`release` branch publishes stable versions; `chore:` commits release a patch,
+`BREAKING CHANGE`/`!` a major. CI syncs to `src/gen` land as `chore: update`
+commits from the Sentio bot.

README.md

@@ -2,74 +2,112 @@
 
 [![npm version](https://badge.fury.io/js/@sentio%2Fapi.svg)](https://npmjs.com/package/@sentio/api) [![Release](https://github.com/sentioxyz/api/actions/workflows/cut-release.yaml/badge.svg)](https://github.com/sentioxyz/api/actions/workflows/cut-release.yaml)
 
+TypeScript client for the [Sentio](https://sentio.xyz) API. The bindings are
+generated from Sentio's protobuf definitions with
+[protobuf-es](https://github.com/bufbuild/protobuf-es) and call the REST API
+through [connect-es](https://github.com/connectrpc/connect-es) with the
+[@sentio/connect-gateway-es](https://github.com/sentioxyz/connect-gateway-es)
+transport — fully typed requests and responses, including server-streaming
+endpoints.
+
+> **v3 is a breaking rewrite.** v2 (`openapi-ts` based: `client.setConfig` +
+> static service classes) is replaced by connect-es style clients. The REST
+> API itself is unchanged; see the examples below for the new shapes. The
+> package is ESM-only and requires Node 20+.
+
 ## Setup
 
 ```
 pnpm add @sentio/api
 ```
 
+Create an API key under your project's settings on
+[app.sentio.xyz](https://app.sentio.xyz).
+
 ## Usage
 
-### Example 1: get project list
+### Example 1: list dashboards
 
 ```ts
-import { client, WebService } from "@sentio/api";
+import { createSentioClient, WebService } from "@sentio/api";
 
-client.setConfig({
-  auth: process.env.SENTIO_API_KEY,
+const web = createSentioClient(WebService, {
+  apiKey: process.env.SENTIO_API_KEY,
 });
-const projects = await WebService.getProjectList();
-console.log(projects);
+const dashboards = await web.listDashboards({
+  ownerName: "sentio",
+  slug: "coinbase",
+});
+console.log(dashboards);
 ```
 
 ### Example 2: insight query
 
 ```ts
-import { client, DataService } from "@sentio/api";
+import { createSentioClient, InsightsService } from "@sentio/api";
 
-client.setConfig({
-  auth: process.env.SENTIO_API_KEY,
+const insights = createSentioClient(InsightsService, {
+  apiKey: process.env.SENTIO_API_KEY,
 });
 
-const res = await DataService.query({
-  path: {
-    owner: "sentio",
-    slug: "coinbase",
+const res = await insights.query({
+  projectOwner: "sentio",
+  projectSlug: "coinbase",
+  timeRange: {
+    start: "now-30d",
+    end: "now",
+    step: 3600,
+    timezone: "America/Los_Angeles",
   },
-  body: {
-    timeRange: {
-      start: "now-30d",
-      end: "now",
-      step: 3600,
-      timezone: "America/Los_Angeles",
-    },
-    limit: 20,
-    queries: [
-      {
-        metricsQuery: {
-          query: "cbETH_price",
-          alias: "",
-          id: "a",
-          labelSelector: {},
-          aggregate: undefined,
-          functions: [],
-          disabled: false,
-        },
-        dataSource: "METRICS",
-        sourceName: "",
+  limit: 20,
+  queries: [
+    {
+      metricsQuery: {
+        query: "cbETH_price",
       },
-    ],
-    formulas: [],
-    cachePolicy: {
-      noCache: false,
-      cacheTtlSecs: 1296000,
-      cacheRefreshTtlSecs: 1800,
     },
-  },
+  ],
 });
 console.log(res);
 ```
 
-## Documentation
+Request messages are plain partial objects (protobuf-es init shapes) — omitted
+fields take their proto defaults.
+
+### Several services over one transport
+
+```ts
+import { createClient, createSentioTransport, AnalyticService, WebService } from "@sentio/api";
+
+const transport = createSentioTransport({ apiKey: process.env.SENTIO_API_KEY });
+const web = createClient(WebService, transport);
+const analytics = createClient(AnalyticService, transport);
+```
+
+### Message and enum types
+
+Each service module exports its request/response types; deep-import them via
+the `gen` subpath:
+
+```ts
+import type { Project } from "@sentio/api/gen/service/common/protos/common_pb.js";
+```
+
+### Options
+
+`createSentioClient` / `createSentioTransport` accept:
+
+- `apiKey` — sent as the `api-key` header.
+- `baseUrl` — defaults to `https://app.sentio.xyz`.
+- everything else from `GatewayTransportOptions`
+  (`headers`, `fetch`, `interceptors`, `defaultTimeoutMs`, ...).
+
+Errors are connect-es `ConnectError`s carrying the mapped gRPC code and the
+server's `google.rpc.Status` details.
+
+## REST / OpenAPI
 
-[Sentio API Reference](https://docs.sentio.xyz/reference)
+The raw REST API is documented at [docs.sentio.xyz](https://docs.sentio.xyz/reference);
+this repository also ships the [OpenAPI spec](./openapi.json) and a generated
+[HTML reference](./doc). Both reflect the same API surface as the TypeScript
+client.

package.json

@@ -6,29 +6,36 @@
     "type": "git",
     "url": "https://github.com/sentioxyz/api.git"
   },
+  "type": "module",
   "exports": {
-    ".": "./dist/src/index.js"
+    ".": "./dist/src/index.js",
+    "./gen/*": "./dist/src/gen/*"
   },
   "files": [
     "{dist,src}",
-    "!dist/test",
-    "!**/.openapi-generator*"
+    "!dist/test"
   ],
   "sideEffects": false,
+  "packageManager": "pnpm@11.3.0",
+  "engines": {
+    "node": ">=24"
+  },
   "scripts": {
     "build": "tsc",
     "test": "tsx --test test/*.test.ts",
     "prepare": "pnpm build"
   },
   "dependencies": {
-    "@hey-api/client-fetch": "^0.8.3"
+    "@bufbuild/protobuf": "^2.12.0",
+    "@connectrpc/connect": "^2.1.2",
+    "@sentio/connect-gateway-es": "^1.0.0"
   },
   "devDependencies": {
-    "@types/node": "^20.14.1",
-    "conventional-changelog-conventionalcommits": "^8.0.0",
+    "@types/node": "^24.13.2",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
     "json": "^11.0.0",
-    "semantic-release": "^24.0.0",
-    "tsx": "^4.12.0",
-    "typescript": "^5.4.5"
+    "semantic-release": "^25.0.5",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
   }
 }