@kivel.io/sdk 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

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.

package/dist/index.d.ts

@@ -76,6 +76,22 @@ export interface KivelLimitDetails {
     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;
@@ -92,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;
@@ -388,7 +405,9 @@ export declare class Kivel {
     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

@@ -17,6 +17,26 @@ export class KivelError extends Error {
         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;
@@ -86,28 +106,89 @@ 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 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 }
-                        : {}),
+        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,
+                    };
                 }
-                : 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);
+                if (pending.length > 16_384)
+                    throw invalid();
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+            reader.releaseLock();
         }
-        return value;
     }
     tools() {
         return this.request('GET', '/api/tools');

package/package.json

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