@kivel.io/sdk 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @kivel.io/sdk
 
+## 0.10.0
+
+### Minor Changes
+
+- ad5805c: Add live event streams to the SDK and use them in the webhook listener.
+
+## 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

@@ -24,6 +24,11 @@ await kivel.remove('inboxes', inbox.id);
 
 `createInbox()` returns a `webhookUrl` that accepts senders without credentials. Reading and waiting still require your workspace key or the private `inspectionToken`. For token-required receiving, pass `{ visibility: 'private' }` and give the sender the returned `accessToken` for its `X-Access-Token` header.
 
+
+Use `stream(['webhook:' + inbox.id], { token, signal })` to receive change notices
+when live updates are available. Fetch the request bodies with the normal inbox
+methods. Pass the last notice's `cursor` as `lastEventId` when reconnecting.
+
 `baseUrl` defaults to `https://kivel.io`; set it to your self-hosted origin.
 Remote origins require HTTPS. The default request timeout is 25 seconds. Requests
 are not automatically retried and redirects are refused.
@@ -44,7 +49,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,55 @@ 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 interface StreamOptions {
+    token?: string;
+    lastEventId?: string;
+    signal?: AbortSignal;
+}
+export type KivelLiveEvent = {
+    type: 'ready';
+    cursor: string;
+} | {
+    type: 'change';
+    cursor: string;
+    topic: string;
+    scopeId: string;
+    id: string;
+    event: string;
+};
 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;
@@ -66,6 +108,7 @@ export declare class Kivel {
     private timeoutMs;
     constructor(options?: ClientOptions);
     request<T = unknown>(method: string, path: string, body?: unknown, resourceToken?: string, headers?: Record<string, string>): Promise<T>;
+    stream(topics: string[], options?: StreamOptions): AsyncGenerator<KivelLiveEvent>;
     tools(): Promise<{
         tools: {
             id: string;
@@ -355,14 +398,16 @@ 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. */
     createInbox(settings?: ResourceSettings): Promise<ResourceCredentials & {
         webhookUrl: string;
     }>;
-    inspectInbox(id: string, token?: string): Promise<unknown>;
+    inspectInbox(id: string, token?: string): Promise<{
+        requests: CapturedRequest[];
+    }>;
     /**
      * Long-polls until the inbox captures a request newer than `after` (any request when omitted).
      * Resolves with `timedOut: true` when nothing arrives; call again to keep waiting.

package/dist/index.js

@@ -5,16 +5,38 @@ 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';
     }
 }
+function apiFailure(response, value) {
+    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;
+    return 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);
+}
 export class Kivel {
     options;
     baseUrl;
@@ -84,27 +106,90 @@ export class Kivel {
                 return text;
             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);
-        }
+        if (!response.ok)
+            throw apiFailure(response, value);
         return value;
     }
+    async *stream(topics, options = {}) {
+        if (!topics.length ||
+            topics.length > 10 ||
+            topics.some((topic) => !topic || /[,\s]/.test(topic)))
+            throw new Error('Choose 1 to 10 live topics.');
+        const query = new URLSearchParams({ topics: topics.join(',') });
+        const headers = new Headers({ Accept: 'text/event-stream' });
+        if (this.options.apiKey)
+            headers.set('Authorization', `Bearer ${this.options.apiKey}`);
+        if (options.token)
+            headers.set('X-Resource-Token', options.token);
+        if (options.lastEventId)
+            headers.set('Last-Event-ID', options.lastEventId);
+        const timeout = AbortSignal.timeout(60_000);
+        const response = await this.fetcher(`${this.baseUrl}/api/stream?${query}`, {
+            headers,
+            redirect: 'error',
+            credentials: 'omit',
+            signal: options.signal ? AbortSignal.any([timeout, options.signal]) : timeout,
+        });
+        if (!response.ok)
+            throw apiFailure(response, await response.json().catch(() => undefined));
+        const invalid = () => new KivelError('The server returned an invalid event stream.', response.status);
+        if (!response.body ||
+            !response.headers.get('content-type')?.startsWith('text/event-stream'))
+            throw invalid();
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let pending = '';
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                pending += decoder.decode(value, { stream: true });
+                for (let end = /\r?\n\r?\n/.exec(pending); end; end = /\r?\n\r?\n/.exec(pending)) {
+                    if (end.index > 16_384)
+                        throw invalid();
+                    const lines = pending.slice(0, end.index).split(/\r?\n/);
+                    pending = pending.slice(end.index + end[0].length);
+                    const cursor = lines.find((line) => line.startsWith('id: '))?.slice(4);
+                    const type = lines.find((line) => line.startsWith('event: '))?.slice(7);
+                    if (!cursor || (type !== 'ready' && type !== 'change'))
+                        continue;
+                    if (type === 'ready') {
+                        yield { type, cursor };
+                        continue;
+                    }
+                    const json = lines
+                        .filter((line) => line.startsWith('data: '))
+                        .map((line) => line.slice(6))
+                        .join('\n');
+                    let data;
+                    try {
+                        data = JSON.parse(json);
+                    }
+                    catch {
+                        throw invalid();
+                    }
+                    if (!data ||
+                        ['topic', 'scopeId', 'id', 'event'].some((key) => typeof data[key] !== 'string'))
+                        throw invalid();
+                    yield {
+                        type,
+                        cursor,
+                        topic: data.topic,
+                        scopeId: data.scopeId,
+                        id: data.id,
+                        event: data.event,
+                    };
+                }
+                if (pending.length > 16_384)
+                    throw invalid();
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+            reader.releaseLock();
+        }
+    }
     tools() {
         return this.request('GET', '/api/tools');
     }

package/package.json

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