@leaflow/sdk 0.2.0 → 0.3.0

package/dist/generated/monitoring/models/index.d.ts

@@ -28,6 +28,7 @@ export * from './assignIncidentRequestBody.js';
 export * from './closeIncidentRequestBody.js';
 export * from './closeIncidentRequestBodyReason.js';
 export * from './countResource.js';
+export * from './cursorPageIncidentActivityResource.js';
 export * from './enableMonitoringRequestBody.js';
 export * from './enableMonitoringRequestBodyAddressKind.js';
 export * from './enableMonitoringRequestBodyAgentMode.js';
@@ -38,14 +39,10 @@ export * from './errorMeta.js';
 export * from './getServerMetricParams.js';
 export * from './getSliReportParams.js';
 export * from './hostInterfaceResource.js';
-export * from './incidentActivityListResponseBody.js';
-export * from './incidentActivityListResponseBodyItems.js';
 export * from './incidentActivityResource.js';
 export * from './incidentActivityResourceActivityType.js';
 export * from './incidentActivityResourceSource.js';
 export * from './incidentFollowerResource.js';
-export * from './incidentListResponseBody.js';
-export * from './incidentListResponseBodyItems.js';
 export * from './incidentResource.js';
 export * from './incidentResourceAcknowledgedAt.js';
 export * from './incidentResourceAssignedAt.js';
@@ -63,6 +60,8 @@ export * from './itemResourceLastCollectedAt.js';
 export * from './itemResourceTags.js';
 export * from './itemResourceValueType.js';
 export * from './itemThresholdResource.js';
+export * from './lengthAwarePageIncidentResource.js';
+export * from './lengthAwarePageServerResource.js';
 export * from './listIncidentTimelineParams.js';
 export * from './listIncidentsAcknowledged.js';
 export * from './listIncidentsClosed.js';
@@ -116,8 +115,6 @@ export * from './sLOResourceSyncStatus.js';
 export * from './scheduleWindowRequest.js';
 export * from './scheduleWindowResource.js';
 export * from './serverEnrollmentResponseBody.js';
-export * from './serverListResponseBody.js';
-export * from './serverListResponseBodyItems.js';
 export * from './serverResource.js';
 export * from './serverResourceAddressKind.js';
 export * from './serverResourceAgentMode.js';

package/dist/generated/monitoring/models/index.js

@@ -28,6 +28,7 @@ export * from './assignIncidentRequestBody.js';
 export * from './closeIncidentRequestBody.js';
 export * from './closeIncidentRequestBodyReason.js';
 export * from './countResource.js';
+export * from './cursorPageIncidentActivityResource.js';
 export * from './enableMonitoringRequestBody.js';
 export * from './enableMonitoringRequestBodyAddressKind.js';
 export * from './enableMonitoringRequestBodyAgentMode.js';
@@ -38,14 +39,10 @@ export * from './errorMeta.js';
 export * from './getServerMetricParams.js';
 export * from './getSliReportParams.js';
 export * from './hostInterfaceResource.js';
-export * from './incidentActivityListResponseBody.js';
-export * from './incidentActivityListResponseBodyItems.js';
 export * from './incidentActivityResource.js';
 export * from './incidentActivityResourceActivityType.js';
 export * from './incidentActivityResourceSource.js';
 export * from './incidentFollowerResource.js';
-export * from './incidentListResponseBody.js';
-export * from './incidentListResponseBodyItems.js';
 export * from './incidentResource.js';
 export * from './incidentResourceAcknowledgedAt.js';
 export * from './incidentResourceAssignedAt.js';
@@ -63,6 +60,8 @@ export * from './itemResourceLastCollectedAt.js';
 export * from './itemResourceTags.js';
 export * from './itemResourceValueType.js';
 export * from './itemThresholdResource.js';
+export * from './lengthAwarePageIncidentResource.js';
+export * from './lengthAwarePageServerResource.js';
 export * from './listIncidentTimelineParams.js';
 export * from './listIncidentsAcknowledged.js';
 export * from './listIncidentsClosed.js';
@@ -116,8 +115,6 @@ export * from './sLOResourceSyncStatus.js';
 export * from './scheduleWindowRequest.js';
 export * from './scheduleWindowResource.js';
 export * from './serverEnrollmentResponseBody.js';
-export * from './serverListResponseBody.js';
-export * from './serverListResponseBodyItems.js';
 export * from './serverResource.js';
 export * from './serverResourceAddressKind.js';
 export * from './serverResourceAgentMode.js';

package/dist/generated/monitoring/models/lengthAwarePageIncidentResource.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Leaflow 监控 用户 API
+ * 用户自己项目里的监控：接入机器、看指标、处理告警、开维护窗口、定可用率目标。
+
+## 怎么带身份
+
+每个请求都要带 `Authorization: Bearer <项目令牌>`。先在 auth.leaflow.net 登录拿到账号令牌，再用它向 IAM 换取项目令牌（`POST /api/v1/projects/{projectId}/token`）。一张项目令牌同时说明当前用户和当前项目。
+
+**路径上没有 `projectId`**：当前项目由令牌决定。
+
+失败时按出路区分：`IDENTITY_EXPIRED` 表示令牌过期，重新换取即可，无需重新登录；`PROJECT_FORBIDDEN` 表示当前账号不是该项目成员；`PROJECT_UNAVAILABLE` 表示项目欠费或正在删除。
+
+## 两组容易混淆的概念
+
+- **停止监控不等于删除**：`POST /servers/{id}/disable` 可逆，历史数据完整保留；`DELETE /servers/{id}` 会连同监控主机、历史数据和这台机器名下的告警一并删除，不可恢复。
+- **告警恢复不等于告警了结**：`incident_status` 表示监控系统是否判定已恢复，`closed_at` 表示是否有人完成了处理。尚未恢复的告警也可以按「已接受的风险」了结。
+
+## PSK 只返回一次
+
+接入和轮换的响应中包含 `tls_psk`，其他任何接口都不会再返回它，请及时保存。遗失后可再轮换一次，代价是被监控的机器需要同步更新一次 agent 配置。
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IncidentResource } from './incidentResource.js';
+export interface LengthAwarePageIncidentResource {
+    /** 这一页的内容 */
+    items: IncidentResource[];
+    /** 这一页最多几条，回显请求里的值 */
+    limit: number;
+    /** 跳过了多少条，回显请求里的值 */
+    offset: number;
+    /** 命中的总条数，不只是这一页 */
+    total: number;
+}

package/dist/generated/monitoring/models/lengthAwarePageIncidentResource.js

@@ -0,0 +1 @@
+export {};

package/dist/generated/monitoring/models/lengthAwarePageServerResource.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Leaflow 监控 用户 API
+ * 用户自己项目里的监控：接入机器、看指标、处理告警、开维护窗口、定可用率目标。
+
+## 怎么带身份
+
+每个请求都要带 `Authorization: Bearer <项目令牌>`。先在 auth.leaflow.net 登录拿到账号令牌，再用它向 IAM 换取项目令牌（`POST /api/v1/projects/{projectId}/token`）。一张项目令牌同时说明当前用户和当前项目。
+
+**路径上没有 `projectId`**：当前项目由令牌决定。
+
+失败时按出路区分：`IDENTITY_EXPIRED` 表示令牌过期，重新换取即可，无需重新登录；`PROJECT_FORBIDDEN` 表示当前账号不是该项目成员；`PROJECT_UNAVAILABLE` 表示项目欠费或正在删除。
+
+## 两组容易混淆的概念
+
+- **停止监控不等于删除**：`POST /servers/{id}/disable` 可逆，历史数据完整保留；`DELETE /servers/{id}` 会连同监控主机、历史数据和这台机器名下的告警一并删除，不可恢复。
+- **告警恢复不等于告警了结**：`incident_status` 表示监控系统是否判定已恢复，`closed_at` 表示是否有人完成了处理。尚未恢复的告警也可以按「已接受的风险」了结。
+
+## PSK 只返回一次
+
+接入和轮换的响应中包含 `tls_psk`，其他任何接口都不会再返回它，请及时保存。遗失后可再轮换一次，代价是被监控的机器需要同步更新一次 agent 配置。
+ * OpenAPI spec version: 1.0.0
+ */
+import type { ServerResource } from './serverResource.js';
+export interface LengthAwarePageServerResource {
+    /** 这一页的内容 */
+    items: ServerResource[];
+    /** 这一页最多几条，回显请求里的值 */
+    limit: number;
+    /** 跳过了多少条，回显请求里的值 */
+    offset: number;
+    /** 命中的总条数，不只是这一页 */
+    total: number;
+}

package/dist/generated/monitoring/models/lengthAwarePageServerResource.js

@@ -0,0 +1 @@
+export {};

package/dist/generated/monitoring/models/listIncidentsParams.d.ts

@@ -29,14 +29,15 @@ import type { ListIncidentsAcknowledged } from './listIncidentsAcknowledged.js';
 import type { ListIncidentsUnassigned } from './listIncidentsUnassigned.js';
 export type ListIncidentsParams = {
     /**
-     * 这一页最多返回多少条，0 表示用默认值
-     * @minimum 0
-     * @maximum 500
+     * 这一页最多返回多少条
+     * @minimum 1
+     * @maximum 200
      */
     limit?: number;
     /**
-     * 跳过多少条
+     * 跳过多少条。要翻得更深请改用游标翻页的接口
      * @minimum 0
+     * @maximum 10000
      */
     offset?: number;
     /**

package/dist/generated/monitoring/models/listServersParams.d.ts

@@ -25,14 +25,15 @@
 import type { ListServersMonitoringStatus } from './listServersMonitoringStatus.js';
 export type ListServersParams = {
     /**
-     * 这一页最多返回多少条，0 表示用默认值
-     * @minimum 0
-     * @maximum 500
+     * 这一页最多返回多少条
+     * @minimum 1
+     * @maximum 200
      */
     limit?: number;
     /**
-     * 跳过多少条
+     * 跳过多少条。要翻得更深请改用游标翻页的接口
      * @minimum 0
+     * @maximum 10000
      */
     offset?: number;
     /**

package/dist/http.d.ts

@@ -1,36 +1,89 @@
 import { type AxiosRequestConfig } from 'axios';
 /** TokenProvider returns the current project token; an empty string sends no token. */
 export type TokenProvider = () => string | Promise<string>;
-/** BaseURLProvider returns the address the current request should go to. */
-export type BaseURLProvider = () => string | Promise<string>;
 export interface ClientOptions {
-    /**
-     * baseURL is the API address, for example https://api.leaflow.net.
-     *
-     * Optional only because getBaseURL may supply it instead; one of the two is
-     * required.
-     */
-    baseURL?: string;
-    /**
-     * getBaseURL is called before every request, and takes precedence over baseURL.
-     *
-     * This package bundles several services, and they do not have to live behind one
-     * address: in development each runs on its own port. A caller that knows which
-     * service it is about to call resolves the address here rather than configuring
-     * one client per service.
-     */
-    getBaseURL?: BaseURLProvider;
+    /** baseURL is one service's address, for example https://compute.leaflow.cloud. */
+    baseURL: string;
     /**
      * getToken is called before every request.
      *
-     * Called each time rather than read once at setup: the project token expires and
-     * is replaced when the active project changes.
+     * Called each time rather than read once at setup: the project token expires,
+     * it is replaced when the active project changes, and in a server it belongs
+     * to whoever is making the current request rather than to the process.
      */
     getToken?: TokenProvider;
     /** timeout in milliseconds. */
     timeout?: number;
 }
-/** configure initialises the SDK. Call it once before use. */
+/** A configured connection to one service. */
+export interface Client {
+    request<T>(config: AxiosRequestConfig): Promise<T>;
+}
+/**
+ * The second argument every generated operation accepts.
+ *
+ * `client` is what makes it possible to talk to more than one service, or to more
+ * than one caller's credentials, from a single process.
+ */
+export interface RequestOptions {
+    client?: Client;
+}
+/**
+ * A connection to one service.
+ *
+ * # Why this exists rather than only `configure`
+ *
+ * `configure` sets module-level state, which quietly rules out two things this SDK
+ * is otherwise well suited to:
+ *
+ *   - **More than one service.** The documents bundled here are separate
+ *     deployments on separate addresses — one host per service through the
+ *     gateway (`iam.leaflow.cloud`, `compute.leaflow.cloud`, …) — and their paths
+ *     are bare `/api/v1/...` with no service prefix: `iam` and `monitoring` both
+ *     own `/api/v1/projects/{id}/...`. One `baseURL` per process therefore means
+ *     one service per process.
+ *   - **More than one caller.** A server handles requests concurrently, and a
+ *     single module-level `getToken` is read at await points interleaved across
+ *     them. Two people signed in at once is enough for one to make a call with
+ *     the other's project token — intermittently, under load, which is the worst
+ *     possible way to find out.
+ *
+ * A client is an ordinary value, so both problems become "hold the right one".
+ *
+ * # Why there is no `getBaseURL` any more
+ *
+ * There was one, and it existed to let the single module-level instance point
+ * somewhere different per call — which is to say, to work around being a
+ * singleton. A client per service answers the same question by construction, and
+ * a resolver that runs before every request is one more place for the address to
+ * be wrong.
+ */
+export declare function createClient(options: ClientOptions): Client;
+/** configure initialises the process-wide fallback client. Call it once. */
 export declare function configure(options: ClientOptions): void;
-/** request is the entry point used by the generated code. */
-export declare function request<T>(config: AxiosRequestConfig): Promise<T>;
+/**
+ * request is the entry point used by the generated code.
+ *
+ * The `options` argument is orval's mutator hook: every generated operation takes
+ * it as its last parameter and passes it straight through, which is what lets a
+ * caller say which client a call belongs to without this module holding any
+ * per-call state.
+ */
+export declare function request<T>(config: AxiosRequestConfig, options?: RequestOptions): Promise<T>;
+/**
+ * A generated namespace with a client already attached.
+ *
+ * `compute.listInstances(params, { client })` at every call site is correct and
+ * tiring, and the tiring part is what makes somebody eventually forget one — at
+ * which point the call silently falls through to the process-wide fallback,
+ * which in a multi-service process points at the wrong service.
+ *
+ *     const compute = withClient(sdk.compute, createClient({ baseURL, getToken }));
+ *     await compute.listInstances({});
+ *
+ * The binding is by position: orval emits `options` as the last declared
+ * parameter of every operation, so `fn.length - 1` is the slot. Arguments the
+ * caller omitted are filled with `undefined` to reach it, and an options object
+ * the caller did pass is merged rather than replaced.
+ */
+export declare function withClient<T extends object>(api: T, client: Client): T;

package/dist/http.js

@@ -4,35 +4,116 @@
 // the active project changes, so setting the Authorization header at each call site
 // would scatter the refresh logic and surface as intermittent 401s.
 import axios from 'axios';
-let instance;
-let provider;
-let baseURLProvider;
-/** configure initialises the SDK. Call it once before use. */
-export function configure(options) {
-    if (!options.baseURL && !options.getBaseURL) {
-        throw new Error('configure requires baseURL or getBaseURL');
-    }
-    provider = options.getToken;
-    baseURLProvider = options.getBaseURL;
-    instance = axios.create({
+/**
+ * A connection to one service.
+ *
+ * # Why this exists rather than only `configure`
+ *
+ * `configure` sets module-level state, which quietly rules out two things this SDK
+ * is otherwise well suited to:
+ *
+ *   - **More than one service.** The documents bundled here are separate
+ *     deployments on separate addresses — one host per service through the
+ *     gateway (`iam.leaflow.cloud`, `compute.leaflow.cloud`, …) — and their paths
+ *     are bare `/api/v1/...` with no service prefix: `iam` and `monitoring` both
+ *     own `/api/v1/projects/{id}/...`. One `baseURL` per process therefore means
+ *     one service per process.
+ *   - **More than one caller.** A server handles requests concurrently, and a
+ *     single module-level `getToken` is read at await points interleaved across
+ *     them. Two people signed in at once is enough for one to make a call with
+ *     the other's project token — intermittently, under load, which is the worst
+ *     possible way to find out.
+ *
+ * A client is an ordinary value, so both problems become "hold the right one".
+ *
+ * # Why there is no `getBaseURL` any more
+ *
+ * There was one, and it existed to let the single module-level instance point
+ * somewhere different per call — which is to say, to work around being a
+ * singleton. A client per service answers the same question by construction, and
+ * a resolver that runs before every request is one more place for the address to
+ * be wrong.
+ */
+export function createClient(options) {
+    const instance = axios.create({
         baseURL: options.baseURL,
         timeout: options.timeout ?? 30_000,
     });
+    return {
+        async request(config) {
+            const token = options.getToken ? await options.getToken() : '';
+            const response = await instance.request({
+                ...config,
+                headers: {
+                    ...config.headers,
+                    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                },
+            });
+            return response.data;
+        },
+    };
 }
-/** request is the entry point used by the generated code. */
-export async function request(config) {
-    if (!instance) {
-        throw new Error('SDK not initialised: call configure({ baseURL }) first');
+/**
+ * The client used when a call does not name one.
+ *
+ * Kept for single-service consumers — a browser talking to one service, a script
+ * — for whom threading a client through every call is ceremony with no payoff. It
+ * is a fallback and not the default anyone should reach for in a server: see
+ * `createClient` for why.
+ */
+let fallback;
+/** configure initialises the process-wide fallback client. Call it once. */
+export function configure(options) {
+    fallback = createClient(options);
+}
+/**
+ * request is the entry point used by the generated code.
+ *
+ * The `options` argument is orval's mutator hook: every generated operation takes
+ * it as its last parameter and passes it straight through, which is what lets a
+ * caller say which client a call belongs to without this module holding any
+ * per-call state.
+ */
+export async function request(config, options) {
+    const client = options?.client ?? fallback;
+    if (!client) {
+        throw new Error('SDK not initialised: pass { client } from createClient(), or call configure({ baseURL }) once for a single-service process');
     }
-    const token = provider ? await provider() : '';
-    const baseURL = baseURLProvider ? await baseURLProvider() : undefined;
-    const response = await instance.request({
-        ...config,
-        ...(baseURL ? { baseURL } : {}),
-        headers: {
-            ...config.headers,
-            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    return client.request(config);
+}
+/**
+ * A generated namespace with a client already attached.
+ *
+ * `compute.listInstances(params, { client })` at every call site is correct and
+ * tiring, and the tiring part is what makes somebody eventually forget one — at
+ * which point the call silently falls through to the process-wide fallback,
+ * which in a multi-service process points at the wrong service.
+ *
+ *     const compute = withClient(sdk.compute, createClient({ baseURL, getToken }));
+ *     await compute.listInstances({});
+ *
+ * The binding is by position: orval emits `options` as the last declared
+ * parameter of every operation, so `fn.length - 1` is the slot. Arguments the
+ * caller omitted are filled with `undefined` to reach it, and an options object
+ * the caller did pass is merged rather than replaced.
+ */
+export function withClient(api, client) {
+    return new Proxy(api, {
+        get(target, property, receiver) {
+            const value = Reflect.get(target, property, receiver);
+            if (typeof value !== 'function') {
+                return value;
+            }
+            const operation = value;
+            return (...args) => {
+                const slot = Math.max(operation.length - 1, 0);
+                const head = args.slice(0, slot);
+                while (head.length < slot) {
+                    head.push(undefined);
+                }
+                const passed = args[slot];
+                return operation(...head, { ...passed, client });
+            };
         },
     });
-    return response.data;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { configure, request } from './http.js';
-export type { ClientOptions, TokenProvider } from './http.js';
+export { configure, createClient, request, withClient } from './http.js';
+export type { Client, ClientOptions, RequestOptions, TokenProvider } from './http.js';
 export * as assistant from './generated/assistant/index.js';
 export * as compute from './generated/compute/index.js';
 export * as iam from './generated/iam/index.js';

package/dist/index.js

@@ -1,13 +1,13 @@
 // Generated by scripts/build-index.mjs. Do not edit.
-export { configure, request } from './http.js';
+export { configure, createClient, request, withClient } from './http.js';
 export * as assistant from './generated/assistant/index.js';
 export * as compute from './generated/compute/index.js';
 export * as iam from './generated/iam/index.js';
 export * as monitoring from './generated/monitoring/index.js';
 /** Service versions the bundled specs were generated from. */
 export const SERVICE_VERSIONS = {
-    assistant: "v0.5.0",
-    compute: "v0.4.0",
-    iam: "v0.22.0",
-    monitoring: "v4.1.0",
+    assistant: "v2.1.1",
+    compute: "v2.1.1",
+    iam: "v0.30.0",
+    monitoring: "v9.0.2",
 };

package/openapi/assistant.version

@@ -1 +1 @@
-v0.5.0
+v2.1.1