@sentio/api 1.0.5-rc.8 → 2.0.0-rc.1

package/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/package.json

@@ -1,30 +1,36 @@
 {
   "name": "@sentio/api",
-  "version": "1.0.5-rc.8",
+  "version": "2.0.0-rc.1",
   "license": "Apache-2.0",
   "repository": {
     "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,
+  "engines": {
+    "node": ">=24"
+  },
   "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"
   },
   "scripts": {
     "build": "tsc",

package/dist/src/client.gen.d.ts

@@ -1,12 +0,0 @@
-import type { ClientOptions } from './types.gen';
-import { type Config, type ClientOptions as DefaultClientOptions } from '@hey-api/client-fetch';
-/**
- * The `createClientConfig()` function will be called on client initialization
- * and the returned object will become the client's initial configuration.
- *
- * You may want to initialize your client this way instead of calling
- * `setConfig()`. This is useful for example if you're using Next.js
- * to ensure your client always has the correct values.
- */
-export type CreateClientConfig<T extends DefaultClientOptions = ClientOptions> = (override?: Config<DefaultClientOptions & T>) => Config<Required<DefaultClientOptions> & T>;
-export declare const client: import("@hey-api/client-fetch").Client;

package/dist/src/client.gen.js

@@ -1,9 +0,0 @@
-"use strict";
-// This file is auto-generated by @hey-api/openapi-ts
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.client = void 0;
-const client_fetch_1 = require("@hey-api/client-fetch");
-exports.client = (0, client_fetch_1.createClient)((0, client_fetch_1.createConfig)({
-    baseUrl: 'https://api.sentio.xyz'
-}));
-//# sourceMappingURL=client.gen.js.map

package/dist/src/client.gen.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.gen.js","sourceRoot":"","sources":["../../src/client.gen.ts"],"names":[],"mappings":";AAAA,qDAAqD;;;AAGrD,wDAA4H;AAY/G,QAAA,MAAM,GAAG,IAAA,2BAAY,EAAC,IAAA,2BAAY,EAAgB;IAC3D,OAAO,EAAE,wBAAwB;CACpC,CAAC,CAAC,CAAC"}

package/dist/src/index.d.ts

@@ -1,3 +0,0 @@
-export * from './types.gen';
-export * from './client.gen';
-export * from './sdk.gen';

package/dist/src/index.js

@@ -1,21 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-// This file is auto-generated by @hey-api/openapi-ts
-__exportStar(require("./types.gen"), exports);
-__exportStar(require("./client.gen"), exports);
-__exportStar(require("./sdk.gen"), exports);
-//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAqD;AACrD,8CAA4B;AAC5B,+CAA6B;AAC7B,4CAA0B"}