uapi-browser-sdk 0.1.13 → 0.1.14

package/README.md

@@ -18,11 +18,13 @@ npm i uapi-browser-sdk
 ```ts
 import { UapiClient } from 'uapi-browser-sdk'
 
-const client = new UapiClient('https://uapis.cn/api/v1')
-const result = await client.social.getSocialQqUserinfo({ qq: '10001' })
+const client = new UapiClient('https://uapis.cn', 'YOUR_API_KEY')
+const result = await client.misc.getMiscHotboard({ type: 'weibo' })
 console.log(result)
 ```
 
+这个接口默认只要传 `type` 就可以拿当前热榜。`time`、`keyword`、`timeStart`、`timeEnd`、`limit`、`sources` 都是按场景再传的可选参数。
+
 ## CDN 引入
 
 `uapi-browser-sdk` 发布在 npm，因而可以直接通过常见 CDN 以 ES Module 方式加载。建议在生产环境固定版本号（`@latest` 仅用于快速试用）。
@@ -33,7 +35,7 @@ console.log(result)
 <script type="module">
   import { UapiClient } from 'https://cdn.jsdelivr.net/npm/uapi-browser-sdk@latest/dist/index.js';
 
-  const client = new UapiClient('https://uapis.cn/api/v1');
+  const client = new UapiClient('https://uapis.cn', 'YOUR_API_KEY');
   const data = await client.social.getSocialQqUserinfo({ qq: '10001' });
   console.log(data);
 </script>
@@ -70,6 +72,63 @@ SDK 采用原生 `fetch`，自动补上 `Authorization` 头且不依赖任何 No
 
 如果你需要查看字段细节或内部逻辑，仓库中的 `./internal` 目录同步保留了由 `openapi-generator` 生成的完整结构体，随时可供参考。
 
+## 响应元信息
+
+每次请求完成后，SDK 会自动把响应 Header 解析成结构化的 `ResponseMeta`，你不用自己拆原始字符串。
+
+成功时可以通过 `client.lastResponseMeta` 读取，失败时可以通过 `err.meta` 读取，两条路径拿到的是同一套字段。
+
+```ts
+import { UapiClient, UapiError } from 'uapi-browser-sdk'
+
+const client = new UapiClient('https://uapis.cn', 'YOUR_API_KEY')
+
+// 成功路径
+await client.social.getSocialQqUserinfo({ qq: '10001' })
+const meta = client.lastResponseMeta
+if (meta) {
+  console.log('这次请求原价:', meta.creditsRequested ?? 0, '积分')
+  console.log('这次实际扣费:', meta.creditsCharged ?? 0, '积分')
+  console.log('特殊计价:', meta.creditsPricing ?? '原价')
+  console.log('余额剩余:', meta.balanceRemainingCents ?? 0, '分')
+  console.log('资源包剩余:', meta.quotaRemainingCredits ?? 0, '积分')
+  console.log('当前有效额度桶:', meta.activeQuotaBuckets ?? 0)
+  console.log('额度用空即停:', meta.stopOnEmpty ?? false)
+  console.log('Key QPS:', meta.billingKeyRateRemaining ?? 0, '/', meta.billingKeyRateLimit ?? 0, meta.billingKeyRateUnit ?? 'req')
+  console.log('Request ID:', meta.requestId)
+}
+
+// 失败路径
+try {
+  await client.social.getSocialQqUserinfo({ qq: '10001' })
+} catch (err) {
+  if (err instanceof UapiError && err.meta) {
+    console.log('Retry-After 秒数:', err.meta.retryAfterSeconds ?? null)
+    console.log('Retry-After 原始值:', err.meta.retryAfterRaw ?? null)
+    console.log('访客 QPS:', err.meta.visitorRateRemaining ?? 0, '/', err.meta.visitorRateLimit ?? 0)
+    console.log('Request ID:', err.meta.requestId)
+  }
+}
+```
+
+常用字段一览：
+
+| 字段 | 说明 |
+|------|------|
+| `creditsRequested` | 这次请求原本要扣多少积分，也就是请求价 |
+| `creditsCharged` | 这次请求实际扣了多少积分 |
+| `creditsPricing` | 特殊计价原因，例如缓存半价 `cache-hit-half-price` |
+| `balanceRemainingCents` | 账户余额剩余（分） |
+| `quotaRemainingCredits` | 资源包剩余积分 |
+| `activeQuotaBuckets` | 当前还有多少个有效额度桶参与计费 |
+| `stopOnEmpty` | 额度耗尽后是否直接停止服务 |
+| `retryAfterSeconds` / `retryAfterRaw` | 限流后的等待时长；当服务端返回 HTTP 时间字符串时看 `retryAfterRaw` |
+| `requestId` | 请求唯一 ID，排障时使用 |
+| `billingKeyRateLimit` / `billingKeyRateRemaining` | Billing Key 当前 QPS 规则的上限与剩余 |
+| `billingIpRateLimit` / `billingIpRateRemaining` | Billing Key 单 IP 当前 QPS 规则的上限与剩余 |
+| `visitorRateLimit` / `visitorRateRemaining` | 访客当前 QPS 规则的上限与剩余 |
+| `rateLimitPolicies` / `rateLimits` | 完整结构化限流策略数据 |
+
 ## 错误模型概览
 
 | HTTP 状态码 | SDK 错误类型 | 附加信息                                     |

package/dist/src/errors.d.ts

@@ -12,6 +12,7 @@ export interface RateLimitStateEntry {
 }
 export interface ResponseMeta {
     requestId?: string;
+    retryAfterRaw?: string;
     retryAfterSeconds?: number;
     debitStatus?: string;
     creditsRequested?: number;
@@ -29,6 +30,21 @@ export interface ResponseMeta {
     quotaRemainingCredits?: number;
     visitorQuotaLimitCredits?: number;
     visitorQuotaRemainingCredits?: number;
+    billingKeyRateLimit?: number;
+    billingKeyRateRemaining?: number;
+    billingKeyRateUnit?: string;
+    billingKeyRateWindowSeconds?: number;
+    billingKeyRateResetAfterSeconds?: number;
+    billingIpRateLimit?: number;
+    billingIpRateRemaining?: number;
+    billingIpRateUnit?: string;
+    billingIpRateWindowSeconds?: number;
+    billingIpRateResetAfterSeconds?: number;
+    visitorRateLimit?: number;
+    visitorRateRemaining?: number;
+    visitorRateUnit?: string;
+    visitorRateWindowSeconds?: number;
+    visitorRateResetAfterSeconds?: number;
     rawHeaders: Record<string, string>;
 }
 export declare class UapiError extends Error {

package/dist/src/errors.js

@@ -161,8 +161,15 @@ export function extractMetaFromHeaders(headers) {
             resetAfterSeconds: parseNumber(item.params.t),
         };
     }
+    const billingKeyRatePolicy = rateLimitPolicies['billing-key-rate'];
+    const billingKeyRateState = rateLimits['billing-key-rate'];
+    const billingIpRatePolicy = rateLimitPolicies['billing-ip-rate'];
+    const billingIpRateState = rateLimits['billing-ip-rate'];
+    const visitorRatePolicy = rateLimitPolicies['visitor-rate'];
+    const visitorRateState = rateLimits['visitor-rate'];
     return {
         requestId: rawHeaders['x-request-id'],
+        retryAfterRaw: rawHeaders['retry-after'],
         retryAfterSeconds: parseNumber(rawHeaders['retry-after']),
         debitStatus: rawHeaders['uapi-debit-status'],
         creditsRequested: parseNumber(rawHeaders['uapi-credits-requested']),
@@ -180,6 +187,21 @@ export function extractMetaFromHeaders(headers) {
         quotaRemainingCredits: rateLimits['billing-quota']?.remaining,
         visitorQuotaLimitCredits: rateLimitPolicies['visitor-quota']?.quota,
         visitorQuotaRemainingCredits: rateLimits['visitor-quota']?.remaining,
+        billingKeyRateLimit: billingKeyRatePolicy?.quota,
+        billingKeyRateRemaining: billingKeyRateState?.remaining,
+        billingKeyRateUnit: billingKeyRatePolicy?.unit ?? billingKeyRateState?.unit,
+        billingKeyRateWindowSeconds: billingKeyRatePolicy?.windowSeconds,
+        billingKeyRateResetAfterSeconds: billingKeyRateState?.resetAfterSeconds,
+        billingIpRateLimit: billingIpRatePolicy?.quota,
+        billingIpRateRemaining: billingIpRateState?.remaining,
+        billingIpRateUnit: billingIpRatePolicy?.unit ?? billingIpRateState?.unit,
+        billingIpRateWindowSeconds: billingIpRatePolicy?.windowSeconds,
+        billingIpRateResetAfterSeconds: billingIpRateState?.resetAfterSeconds,
+        visitorRateLimit: visitorRatePolicy?.quota,
+        visitorRateRemaining: visitorRateState?.remaining,
+        visitorRateUnit: visitorRatePolicy?.unit ?? visitorRateState?.unit,
+        visitorRateWindowSeconds: visitorRatePolicy?.windowSeconds,
+        visitorRateResetAfterSeconds: visitorRateState?.resetAfterSeconds,
         rawHeaders,
     };
 }

package/dist/src/index.js

@@ -1,8 +1,13 @@
 import { extractMetaFromHeaders, mapError } from './errors.js';
 export { UapiError, mapError, extractMetaFromHeaders } from './errors.js';
+const API_PREFIX = '/api/v1';
+function normalizeBaseURL(baseURL) {
+    const trimmed = baseURL.replace(/\/+$/, '');
+    return trimmed.endsWith(API_PREFIX) ? trimmed.slice(0, -API_PREFIX.length) : trimmed;
+}
 export class UapiClient {
     constructor(baseURL, token) {
-        this.baseURL = baseURL;
+        this.baseURL = normalizeBaseURL(baseURL);
         this.token = token;
         const clipzyZaiXianJianTieBan = new ClipzyZaiXianJianTieBanApi(this);
         this.clipzyZaiXianJianTieBan = clipzyZaiXianJianTieBan;
@@ -57,7 +62,7 @@ export class UapiClient {
         return this._lastResponseMeta;
     }
     async _request(method, path, params, body, headers, responseKind = 'json') {
-        const url = new URL(this.baseURL.replace(/\/$/, '') + path);
+        const url = new URL(this.baseURL + path);
         if (params) {
             Object.entries(params).forEach(([key, value]) => {
                 if (value !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uapi-browser-sdk",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/src/errors.ts

@@ -14,6 +14,7 @@ export interface RateLimitStateEntry {
 
 export interface ResponseMeta {
   requestId?: string
+  retryAfterRaw?: string
   retryAfterSeconds?: number
   debitStatus?: string
   creditsRequested?: number
@@ -31,6 +32,21 @@ export interface ResponseMeta {
   quotaRemainingCredits?: number
   visitorQuotaLimitCredits?: number
   visitorQuotaRemainingCredits?: number
+  billingKeyRateLimit?: number
+  billingKeyRateRemaining?: number
+  billingKeyRateUnit?: string
+  billingKeyRateWindowSeconds?: number
+  billingKeyRateResetAfterSeconds?: number
+  billingIpRateLimit?: number
+  billingIpRateRemaining?: number
+  billingIpRateUnit?: string
+  billingIpRateWindowSeconds?: number
+  billingIpRateResetAfterSeconds?: number
+  visitorRateLimit?: number
+  visitorRateRemaining?: number
+  visitorRateUnit?: string
+  visitorRateWindowSeconds?: number
+  visitorRateResetAfterSeconds?: number
   rawHeaders: Record<string, string>
 }
 
@@ -192,8 +208,16 @@ export function extractMetaFromHeaders(headers: Headers | Record<string, unknown
     }
   }
 
+  const billingKeyRatePolicy = rateLimitPolicies['billing-key-rate']
+  const billingKeyRateState = rateLimits['billing-key-rate']
+  const billingIpRatePolicy = rateLimitPolicies['billing-ip-rate']
+  const billingIpRateState = rateLimits['billing-ip-rate']
+  const visitorRatePolicy = rateLimitPolicies['visitor-rate']
+  const visitorRateState = rateLimits['visitor-rate']
+
   return {
     requestId: rawHeaders['x-request-id'],
+    retryAfterRaw: rawHeaders['retry-after'],
     retryAfterSeconds: parseNumber(rawHeaders['retry-after']),
     debitStatus: rawHeaders['uapi-debit-status'],
     creditsRequested: parseNumber(rawHeaders['uapi-credits-requested']),
@@ -211,6 +235,21 @@ export function extractMetaFromHeaders(headers: Headers | Record<string, unknown
     quotaRemainingCredits: rateLimits['billing-quota']?.remaining,
     visitorQuotaLimitCredits: rateLimitPolicies['visitor-quota']?.quota,
     visitorQuotaRemainingCredits: rateLimits['visitor-quota']?.remaining,
+    billingKeyRateLimit: billingKeyRatePolicy?.quota,
+    billingKeyRateRemaining: billingKeyRateState?.remaining,
+    billingKeyRateUnit: billingKeyRatePolicy?.unit ?? billingKeyRateState?.unit,
+    billingKeyRateWindowSeconds: billingKeyRatePolicy?.windowSeconds,
+    billingKeyRateResetAfterSeconds: billingKeyRateState?.resetAfterSeconds,
+    billingIpRateLimit: billingIpRatePolicy?.quota,
+    billingIpRateRemaining: billingIpRateState?.remaining,
+    billingIpRateUnit: billingIpRatePolicy?.unit ?? billingIpRateState?.unit,
+    billingIpRateWindowSeconds: billingIpRatePolicy?.windowSeconds,
+    billingIpRateResetAfterSeconds: billingIpRateState?.resetAfterSeconds,
+    visitorRateLimit: visitorRatePolicy?.quota,
+    visitorRateRemaining: visitorRateState?.remaining,
+    visitorRateUnit: visitorRatePolicy?.unit ?? visitorRateState?.unit,
+    visitorRateWindowSeconds: visitorRatePolicy?.windowSeconds,
+    visitorRateResetAfterSeconds: visitorRateState?.resetAfterSeconds,
     rawHeaders,
   }
 }

package/src/index.ts

@@ -2,6 +2,14 @@ import type * as Internal from '../internal/src/index.js'
 import { UapiError, type ResponseMeta, extractMetaFromHeaders, mapError } from './errors.js'
 export { UapiError, mapError, extractMetaFromHeaders } from './errors.js'
 export type { RateLimitPolicyEntry, RateLimitStateEntry, ResponseMeta } from './errors.js'
+
+const API_PREFIX = '/api/v1'
+
+function normalizeBaseURL(baseURL: string): string {
+  const trimmed = baseURL.replace(/\/+$/, '')
+  return trimmed.endsWith(API_PREFIX) ? trimmed.slice(0, -API_PREFIX.length) : trimmed
+}
+
 export type GetClipzyGetResponse =
   Internal.GetClipzyGet200Response
 export interface GetClipzyGetArgs {
@@ -830,7 +838,7 @@ export class UapiClient {
   readonly "智能搜索": ZhiNengSouSuoApi
 
   constructor(baseURL: string, token?: string) {
-    this.baseURL = baseURL
+    this.baseURL = normalizeBaseURL(baseURL)
     this.token = token
     const clipzyZaiXianJianTieBan = new ClipzyZaiXianJianTieBanApi(this)
     this.clipzyZaiXianJianTieBan = clipzyZaiXianJianTieBan
@@ -894,7 +902,7 @@ export class UapiClient {
     headers?: Record<string, string>,
     responseKind: 'json' | 'text' | 'arrayBuffer' = 'json',
   ) {
-    const url = new URL(this.baseURL.replace(/\/$/, '') + path)
+    const url = new URL(this.baseURL + path)
     if (params) {
       Object.entries(params).forEach(([key, value]) => {
         if (value !== undefined) {