@kivel.io/sdk 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @kivel.io/sdk
 
+## 0.9.0
+
+### Minor Changes
+
+- fde4ed4: Show clear messages and structured details for plan allowances and request rate limits.
+- fde4ed4: Type the usage response, including workspace allowance counters and reset times when the server provides them.
+
+### Patch Changes
+
+- fde4ed4: Read the machine code from the new `code` field while retaining support for older servers. The HTTP `error` field remains a readable message. Exhausted hosted tool, email, and resource allowances return 402. Request rate limits return 429. Timed limits include `Retry-After`, which the SDK and CLI expose to callers.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -44,7 +44,7 @@ write a local credential file. Do not log responses that contain keys or tokens.
 
 [Method reference](https://kivel.io/docs/sdk/) ·
 [Agent workflows](https://kivel.io/docs/agent-workflows/) ·
-[Plan limits](https://kivel.io/plans/)
+[Plan limits](https://kivel.io/pricing/)
 
 Licensed under Apache-2.0. Support: support@kivel.io.
 

package/dist/index.d.ts

@@ -51,13 +51,39 @@ export interface Execution {
         resetsAt: string;
     };
 }
+export interface KivelUsage {
+    plan: 'anonymous' | 'free' | 'pro' | 'team';
+    limits: Record<string, unknown>;
+    runsToday: number;
+    resetsAt: string;
+    period?: {
+        start: string;
+        end: string;
+    };
+    items?: {
+        key: string;
+        label: string;
+        unit: 'count' | 'bytes';
+        used: number;
+        max: number;
+        resetsAt?: string;
+    }[];
+}
+export interface KivelLimitDetails {
+    code: 'limit_reached' | 'rate_limited';
+    limit: string;
+    used?: number;
+    max?: number;
+    plan?: KivelUsage['plan'];
+}
 export declare class KivelError extends Error {
     readonly status: number;
     readonly requestId?: string | undefined;
     readonly retryAfter?: number | undefined;
     readonly requiredPlan?: string | undefined;
     readonly upgradeUrl?: string | undefined;
-    constructor(message: string, status: number, requestId?: string | undefined, retryAfter?: number | undefined, requiredPlan?: string | undefined, upgradeUrl?: string | undefined);
+    readonly limitDetails?: KivelLimitDetails | undefined;
+    constructor(message: string, status: number, requestId?: string | undefined, retryAfter?: number | undefined, requiredPlan?: string | undefined, upgradeUrl?: string | undefined, limitDetails?: KivelLimitDetails | undefined);
 }
 export declare class Kivel {
     private options;
@@ -355,7 +381,7 @@ export declare class Kivel {
     inboxDeliveries(id: string, token?: string): Promise<unknown>;
     private waitTimeout;
     private waitQuery;
-    usage(): Promise<unknown>;
+    usage(): Promise<KivelUsage>;
     resources(): Promise<unknown>;
     /** Senders can POST to webhookUrl without credentials by default. Inspection stays private.
      * Set visibility to private to require X-Access-Token on incoming webhooks. */

package/dist/index.js

@@ -5,13 +5,15 @@ export class KivelError extends Error {
     retryAfter;
     requiredPlan;
     upgradeUrl;
-    constructor(message, status, requestId, retryAfter, requiredPlan, upgradeUrl) {
+    limitDetails;
+    constructor(message, status, requestId, retryAfter, requiredPlan, upgradeUrl, limitDetails) {
         super(message);
         this.status = status;
         this.requestId = requestId;
         this.retryAfter = retryAfter;
         this.requiredPlan = requiredPlan;
         this.upgradeUrl = upgradeUrl;
+        this.limitDetails = limitDetails;
         this.name = 'KivelError';
     }
 }
@@ -85,23 +87,25 @@ export class Kivel {
             throw new KivelError('The server returned an invalid response.', response.status, response.headers.get('x-request-id') ?? undefined);
         }
         if (!response.ok) {
-            const message = value &&
-                typeof value === 'object' &&
-                'error' in value &&
-                typeof value.error === 'string'
-                ? value.error
-                : `Request failed (${response.status}).`;
-            throw new KivelError(message, response.status, response.headers.get('x-request-id') ?? undefined, Number(response.headers.get('retry-after')) || undefined, value &&
-                typeof value === 'object' &&
-                'requiredPlan' in value &&
-                typeof value.requiredPlan === 'string'
-                ? value.requiredPlan
-                : undefined, value &&
-                typeof value === 'object' &&
-                'upgradeUrl' in value &&
-                typeof value.upgradeUrl === 'string'
-                ? value.upgradeUrl
-                : undefined);
+            const error = value && typeof value === 'object' ? value : {};
+            const code = error.code ?? error.error;
+            const details = (code === 'limit_reached' || code === 'rate_limited') &&
+                typeof error.limit === 'string'
+                ? {
+                    code,
+                    limit: error.limit,
+                    ...(typeof error.used === 'number' ? { used: error.used } : {}),
+                    ...(typeof error.max === 'number' ? { max: error.max } : {}),
+                    ...(['anonymous', 'free', 'pro', 'team'].some((plan) => plan === error.plan)
+                        ? { plan: error.plan }
+                        : {}),
+                }
+                : undefined;
+            throw new KivelError(typeof error.message === 'string'
+                ? error.message
+                : typeof error.error === 'string'
+                    ? error.error
+                    : `Request failed (${response.status}).`, response.status, response.headers.get('x-request-id') ?? undefined, Number(response.headers.get('retry-after')) || undefined, typeof error.requiredPlan === 'string' ? error.requiredPlan : undefined, typeof error.upgradeUrl === 'string' ? error.upgradeUrl : undefined, details);
         }
         return value;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kivel.io/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "exports": {
     ".": {