@ycodium-ai/plugin-api 0.2.2169 → 0.2.2488

package/dist/account-usage.d.ts

@@ -0,0 +1,191 @@
+/**
+ * `@ycodium-ai/plugin-api/account-usage` —— provider 实例**自己登录的账号**的额度。
+ *
+ * 两半，都只含 `type` / `interface`，没有运行时值：
+ * - 读法声明（{@link PluginAccountUsageProbe}，执行器名片上的 `accountUsage`）：纯数据的
+ *   请求与字段映射；凭据、HTTP 和缓存由宿主持有。
+ * - 读出来的**窄事实类型**：宿主 `AccountUsageMetric` / `AccountUsageSnapshot` /
+ *   `AccountUsageCapability` 的结构子集——宿主模型必须可赋值到这里，反向不保证。
+ *   不含格式化规则、缓存、轮询或查询策略。
+ *
+ * 插件不得 import contracts / runtime；UI 组件用 `import type`。宿主按本文件实现
+ * `ConversationHostData.useAccountUsage` 与 `ctx.providers.readAccountUsage` 的返回值。
+ *
+ * @module @ycodium-ai/plugin-api/account-usage
+ */
+/** 请求头里引用登录凭据的哪一部分。 */
+export interface PluginAccountUsageHeader {
+    readonly credential: "accessToken" | "accountId";
+    readonly prefix?: string;
+    readonly optional?: boolean;
+}
+export type PluginAccountUsageText = {
+    readonly value: string;
+} | {
+    readonly path: string;
+};
+export type PluginAccountUsageMappingUnit = {
+    readonly kind: "money";
+    readonly currency: PluginAccountUsageText;
+    readonly precision: number;
+} | {
+    readonly kind: "credits" | "requests" | "tokens";
+    readonly nativeUnit: string;
+} | {
+    readonly kind: "percent";
+    readonly direction: "used" | "remaining";
+};
+/** path 使用 JSON Pointer；缺失或不能解码的值保持未知。金额保留原生金额单位。 */
+export interface PluginAccountUsageMapping {
+    /**
+     * 数值指针全都落空时按 0 算，而不是把整行丢掉。用在「窗口确实存在、只是还没用掉
+     * 配额」的情况（厂商这时干脆不发那个百分比字段）。要与 `optional` 一起用。
+     */
+    readonly zeroWhenAbsent?: boolean;
+    readonly id: string;
+    readonly optional?: boolean;
+    readonly rowsAt?: string;
+    readonly idAt?: string;
+    readonly kind: AccountUsageMetricKind;
+    readonly scope: AccountUsageScopeKind;
+    readonly unit: PluginAccountUsageMappingUnit;
+    readonly usedAt?: string;
+    readonly remainingAt?: string;
+    readonly limitAt?: string;
+    readonly unlimitedAt?: string;
+    readonly labelAt?: string;
+    readonly windowSecondsAt?: string;
+    /**
+     * 响应里没有、但厂商知识里有的两样：窗口的名字与长度。有 `*At` 指针时以响应为准。
+     * `label` 是**标识**不是文案：宿主与界面按它查 catalog，查不到才把原文当文案显示。
+     */
+    readonly label?: string;
+    readonly windowSeconds?: number;
+    readonly resetsAt?: {
+        readonly path: string;
+        readonly format: "epoch-seconds" | "iso";
+    };
+}
+export interface PluginAccountUsageRequest {
+    readonly url: string;
+    /** 缺席 = GET；POST 带 `body`（固定 JSON 文本，宿主原样发，不插值）。 */
+    readonly method?: "GET" | "POST";
+    readonly body?: string;
+    readonly headers: Readonly<Record<string, string | PluginAccountUsageHeader>>;
+}
+export interface PluginAccountUsageProbe {
+    readonly id: string;
+    /** 读哪一家的登录凭据；宿主按它选凭据文件与投递受众。 */
+    readonly credentialKind: "codex-chatgpt" | "claude-oauth";
+    readonly request: PluginAccountUsageRequest;
+    /**
+     * 额外的请求。厂商把一份额度拆在几个地址上时用，而一只手只能声明一条读法。
+     *
+     * 每条必须与主请求同源。取回来的内容挂在 `/@requests/<id>/body` 下，指针照常写；
+     * 主请求的内容仍在根上。
+     */
+    readonly extraRequests?: readonly {
+        readonly id: string;
+        readonly request: PluginAccountUsageRequest;
+    }[];
+    readonly metrics: readonly PluginAccountUsageMapping[];
+    readonly ttlMs: number;
+    readonly cooldownMs: number;
+}
+export type AccountUsageRefreshOutcome = "fresh" | "partial" | "joined-inflight" | "rate-limited" | "offline" | "unsupported" | "error";
+export type AccountUsageMetricKind = "balance" | "credits" | "quota-window" | "spend-cap" | "rate-limit";
+export type AccountUsageCapabilityStatus = "supported" | "unsupported" | "unknown";
+export type AccountUsageScopeKind = "account" | "org";
+export type AccountUsageMetricStatus = "available" | "pending" | "unmeterable" | "expired" | "error";
+export type AccountUsageMetricFreshness = "fresh" | "stale" | "unknown";
+/** 凭据身份：稳定 id + 单调 revision，不能用邮箱或路径代替。 */
+export interface AccountUsageCredentialIdentity {
+    readonly id: string;
+    readonly revision: number;
+}
+export type AccountUsageUnit = {
+    readonly kind: "money";
+    readonly currency: string;
+    readonly precision: number;
+} | {
+    readonly kind: "credits" | "requests" | "tokens";
+    readonly nativeUnit: string;
+} | {
+    readonly kind: "percent";
+    readonly direction: "used" | "remaining";
+};
+export interface AccountUsageCapability {
+    readonly status: AccountUsageCapabilityStatus;
+    readonly ttlMs: number;
+    readonly cooldownMs: number;
+}
+export interface AccountUsageMetric {
+    readonly metricId: string;
+    readonly kind: AccountUsageMetricKind;
+    readonly scope: AccountUsageScopeKind;
+    readonly nativeLabel: string | null;
+    readonly used: number | null;
+    readonly remaining: number | null;
+    readonly limit: number | null;
+    readonly unit: AccountUsageUnit;
+    readonly unlimited: boolean | null;
+    /** 窗口长度；说不清时为 null。 */
+    readonly windowMs: number | null;
+    readonly resetsAt: string | null;
+    readonly status: AccountUsageMetricStatus;
+    readonly freshness: AccountUsageMetricFreshness;
+    readonly fetchedAt: string | null;
+    readonly lastAttemptAt: string | null;
+    readonly expiresAt: string | null;
+    readonly errorReason: string | null;
+}
+export interface AccountUsageSnapshot {
+    readonly environmentId: string;
+    readonly instanceId: string;
+    readonly credentialIdentity: AccountUsageCredentialIdentity;
+    readonly snapshotRevision: number;
+    readonly refreshing: boolean;
+    readonly metrics: ReadonlyArray<AccountUsageMetric>;
+}
+/** 手动刷新完成结果。进行中的合并由宿主返回 `joined-inflight`，插件不假装成功。 */
+export interface AccountUsageRefreshResult {
+    readonly outcome: AccountUsageRefreshOutcome;
+    readonly retryAt: string | null;
+}
+/**
+ * composer 额度区的宿主注入面。数据全部来自这份 props：插件不另建缓存、
+ * 不轮询、不调 Usage 插件、不读默认机器账户。`onRefresh` 必须是宿主接上的
+ * 真实查询；缺席整份 props，不要塞空回调。
+ *
+ * 顶层 `credentialIdentity` 在尚未取得凭据或不支持读取时为 null，界面不得
+ * 发明身份 id。真 snapshot 仍携带真实 identity。
+ * `queryKey` 由宿主按观察范围（这个实例）生成，插件只当不透明刷新代次键，不展示、不解析。
+ */
+export interface ConversationComposerAccountUsage {
+    readonly environmentId: string;
+    readonly instanceId: string;
+    readonly queryKey: string;
+    readonly credentialIdentity: AccountUsageCredentialIdentity | null;
+    /** 额度区标题：这个实例的显示名。 */
+    readonly instanceLabel: string;
+    readonly capability: AccountUsageCapability;
+    readonly snapshot: AccountUsageSnapshot | null;
+    readonly loading: boolean;
+    readonly error: string | null;
+    readonly onRefresh: () => Promise<AccountUsageRefreshResult>;
+}
+/**
+ * 按**实例**读到的自管登录额度（`ctx.providers.readAccountUsage`）。
+ *
+ * 与 composer 那份是同一份宿主快照：同一条探针、同一个缓存，插件不自己出网、不自己
+ * 读凭据。`supported` 为 false 表示宿主认不得这只手的自管登录（或它被停用、已删除），
+ * 此时不该为它出额度行；`reasonCode` 是宿主给的原因码，原样用于区分「没登录」与
+ * 「读不到」。`metrics` 的 `nativeLabel` 是**标识**不是文案，界面自己查 catalog。
+ */
+export interface PluginAccountUsage {
+    readonly instanceId: string;
+    readonly supported: boolean;
+    readonly reasonCode: string | null;
+    readonly metrics: ReadonlyArray<AccountUsageMetric>;
+}
+//# sourceMappingURL=account-usage.d.ts.map

package/dist/account-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-usage.d.ts","sourceRoot":"","sources":["../src/account-usage.ts"],"names":[],"mappings":"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"}

package/dist/account-usage.js

@@ -0,0 +1,17 @@
+/**
+ * `@ycodium-ai/plugin-api/account-usage` —— provider 实例**自己登录的账号**的额度。
+ *
+ * 两半，都只含 `type` / `interface`，没有运行时值：
+ * - 读法声明（{@link PluginAccountUsageProbe}，执行器名片上的 `accountUsage`）：纯数据的
+ *   请求与字段映射；凭据、HTTP 和缓存由宿主持有。
+ * - 读出来的**窄事实类型**：宿主 `AccountUsageMetric` / `AccountUsageSnapshot` /
+ *   `AccountUsageCapability` 的结构子集——宿主模型必须可赋值到这里，反向不保证。
+ *   不含格式化规则、缓存、轮询或查询策略。
+ *
+ * 插件不得 import contracts / runtime；UI 组件用 `import type`。宿主按本文件实现
+ * `ConversationHostData.useAccountUsage` 与 `ctx.providers.readAccountUsage` 的返回值。
+ *
+ * @module @ycodium-ai/plugin-api/account-usage
+ */
+export {};
+//# sourceMappingURL=account-usage.js.map

package/dist/account-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-usage.js","sourceRoot":"","sources":["../src/account-usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}