@kivel.io/sdk 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @kivel.io/sdk
 
+## 0.11.0
+
+### Minor Changes
+
+- e137d14: Add email search filters, resumable wait cursors and checkpoints before triggering new mail. Add message inspection, triage and email forwarding history.
+
+## 0.10.1
+
+### Patch Changes
+
+- 10de14b: Publish releases to the npm latest tag, so `npm install @kivel.io/sdk` and `npm install --global @kivel.io/cli` install the newest version. Install instructions no longer need `@beta`.
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -6,11 +6,10 @@ for coding agents. Requires Node.js 22.13+ or a compatible fetch-based runtime.
 The published package is ESM; use `import`, not CommonJS `require`.
 
 ```sh
-npm install @kivel.io/sdk@beta
+npm install @kivel.io/sdk
 ```
 
-Use the explicit beta tag for the current beta channel. Pin an exact version
-when you need reproducible application builds.
+Pin an exact version when you need reproducible application builds.
 
 ```ts
 import { Kivel, KivelError } from '@kivel.io/sdk';
@@ -24,7 +23,6 @@ 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.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export * from './types.js';
-import type { Authenticator, AuthenticatorInput, TotpCode, EmailAttachmentLink, OAuthProviderInput, OAuthProvider, CreatedOAuthProvider, AgentLogin, AgentToken, AgentTrial, Approval, ApprovalInput, EmailInbox, EmailMessage, EmailContent, EmailThread, EmailThreadsPage, EmailDraft, EmailRules, MemoryEntry, Monitor, MonitorInput, WaitOptions } from './types.js';
+import type { Authenticator, AuthenticatorInput, TotpCode, EmailAttachmentLink, OAuthProviderInput, OAuthProvider, CreatedOAuthProvider, AgentLogin, AgentToken, AgentTrial, Approval, ApprovalInput, EmailInbox, EmailMessage, EmailSearchOptions, EmailWaitOptions, EmailContent, EmailThread, EmailThreadsPage, EmailDraft, EmailRules, MemoryEntry, Monitor, MonitorInput } from './types.js';
 export interface ClientOptions {
     baseUrl?: string | undefined;
     apiKey?: string | undefined;
@@ -257,14 +257,22 @@ export declare class Kivel {
     }>;
     emailForwarding(id: string, url: string | null, token?: string): Promise<{
         forwardingUrl: string | null;
+        signingSecret?: string;
+    }>;
+    emailDeliveries(id: string): Promise<{
+        deliveries: import('./types.js').EmailDelivery[];
     }>;
     emailInbox(id: string, token?: string): Promise<EmailInbox>;
-    emails(id: string, token?: string): Promise<{
+    emails(id: string, tokenOrOptions?: string | EmailSearchOptions): Promise<{
         messages: EmailMessage[];
+        nextCursor?: string | null;
     }>;
-    waitForEmail(id: string, options?: WaitOptions): Promise<{
+    emailMessage(id: string, messageId: string, token?: string): Promise<EmailMessage>;
+    updateEmailMessage(id: string, messageId: string, update: import('./types.js').EmailMessageUpdate): Promise<EmailMessage>;
+    waitForEmail(id: string, options?: EmailWaitOptions): Promise<{
         timedOut: boolean;
         messages: EmailMessage[];
+        nextCursor?: string;
     }>;
     memorySet<T>(namespace: string, key: string, value: T, ttlSeconds?: number): Promise<Omit<MemoryEntry<T>, "value">>;
     memoryGet<T = unknown>(namespace: string, key: string): Promise<MemoryEntry<T>>;

package/dist/index.js

@@ -371,14 +371,26 @@ export class Kivel {
     emailForwarding(id, url, token) {
         return this.request('PUT', `/api/email-inboxes/${encodeURIComponent(id)}/forwarding`, { url }, token);
     }
+    emailDeliveries(id) {
+        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/deliveries`);
+    }
     emailInbox(id, token) {
         return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}`, undefined, token);
     }
-    emails(id, token) {
-        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/messages`, undefined, token);
+    emails(id, tokenOrOptions) {
+        const settings = typeof tokenOrOptions === 'string' ? { token: tokenOrOptions } : (tokenOrOptions ?? {});
+        const { token, ...filters } = settings;
+        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/messages${query(filters)}`, undefined, token);
+    }
+    emailMessage(id, messageId, token) {
+        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/messages/${encodeURIComponent(messageId)}`, undefined, token);
+    }
+    updateEmailMessage(id, messageId, update) {
+        return this.request('PATCH', `/api/email-inboxes/${encodeURIComponent(id)}/messages/${encodeURIComponent(messageId)}`, update);
     }
     waitForEmail(id, options = {}) {
-        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/wait${this.waitQuery(options)}`, undefined, options.token);
+        const { token, ...filters } = options;
+        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/wait${query({ ...filters, timeoutSeconds: this.waitTimeout(options.timeoutSeconds) })}`, undefined, token);
     }
     memorySet(namespace, key, value, ttlSeconds) {
         return this.request('PUT', memoryPath(namespace, key), {

package/dist/types.d.ts

@@ -1,3 +1,24 @@
+export interface EmailFilters {
+    from?: string | undefined;
+    mailFrom?: string | undefined;
+    subject?: string | undefined;
+    text?: string | undefined;
+    hasCode?: boolean | undefined;
+    hasLink?: boolean | undefined;
+    hasAttachment?: boolean | undefined;
+    read?: boolean | undefined;
+    label?: string | undefined;
+}
+export interface EmailSearchOptions extends EmailFilters {
+    token?: string | undefined;
+    cursor?: string | undefined;
+    limit?: number | undefined;
+}
+export interface EmailWaitOptions extends WaitOptions, EmailFilters {
+    cursor?: string | undefined;
+    limit?: number | undefined;
+    checkpoint?: boolean | undefined;
+}
 export interface WaitOptions {
     token?: string;
     after?: string;
@@ -35,6 +56,15 @@ export interface AgentTrial {
     };
     instructions: string;
 }
+export interface EmailDelivery {
+    messageId: string;
+    pending: boolean;
+    attempts: {
+        at: string;
+        status?: number;
+        error?: string;
+    }[];
+}
 export interface EmailInbox {
     id: string;
     address: string;
@@ -95,10 +125,13 @@ export interface EmailMessage {
     }[];
     direction?: 'inbound' | 'outbound';
     deliveryStatus?: 'pending' | 'sent';
+    read?: boolean;
+    labels?: string[];
     messageId?: string;
     inReplyTo?: string;
     references?: string[];
 }
+export type EmailMessageUpdate = Pick<EmailMessage, 'read' | 'labels'>;
 export interface EmailContent {
     to: string[];
     cc?: string[];
@@ -117,6 +150,11 @@ export interface EmailThreadSummary {
     lastAt: string;
     from: string;
     messageCount: number;
+    unread?: boolean;
+    hasCode?: boolean;
+    hasLink?: boolean;
+    hasAttachment?: boolean;
+    labels?: string[];
 }
 export interface EmailThread extends EmailThreadSummary {
     messages: EmailMessage[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kivel.io/sdk",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "exports": {
     ".": {
@@ -34,7 +34,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "beta"
+    "tag": "latest"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",