@kivel.io/sdk 0.6.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @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
+
+- 7290344: Add test wallets, x402 paywalls and mock checkouts with approval-aware payments, ledgers and test outcome controls.
+
+## 0.7.0
+
+### Minor Changes
+
+- 7cbd3fc: Add workspace credential storage, password generation and approved reveals.
+
 ## 0.6.1
 
 ### Patch 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.
 
@@ -85,3 +85,14 @@ await kivel.deleteOAuthProvider(provider.id);
 `oauthProviders()` lists workspace providers; `updateOAuthProvider(id, config)` replaces
 the users, claims and test scenario. Endpoint use is public; management stays private.
 See the [OAuth guide](https://kivel.io/docs/mock-oauth/) for token flows and failure scenarios.
+
+## Workspace vault
+
+Use `saveCredential({ name, url, username })` to generate and store a password, or
+include `password` to save one you already have. The generated value is returned
+once. `credentials()` and `credential(id)` return metadata.
+`revealCredential(id)` requests human approval by default. Wait with
+`waitForApproval(approvalId)`, then repeat the reveal with that approval ID.
+Each approval permits one reveal by the same caller. Only signed-in owners and
+admins can change `agentMayRead`. Use `generatePassword(length)` for a standalone
+password, `updateCredential(id, changes)` to edit, and `deleteCredential(id)` to remove it.

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;
@@ -123,6 +149,57 @@ export declare class Kivel {
     deleteAuthenticator(id: string): Promise<void>;
     getEmailAttachment(id: string, messageId: string, attachmentId: string): Promise<EmailAttachmentLink>;
     downloadEmailAttachment(id: string, messageId: string, attachmentId: string): Promise<Uint8Array>;
+    createTestWallet(input: import('./types.js').TestWalletInput): Promise<import("./types.js").TestPaymentResource>;
+    createTestPaywall(input: import('./types.js').TestPaywallInput): Promise<import("./types.js").TestPaymentResource>;
+    createTestCheckout(input: import('./types.js').TestCheckoutInput): Promise<import("./types.js").TestPaymentResource & {
+        webhookSecret: string;
+    }>;
+    testPayments(kind: 'wallets' | 'paywalls' | 'checkouts'): Promise<{
+        testMode: true;
+        resources: import('./types.js').TestPaymentResource[];
+    }>;
+    testPayment(kind: 'wallets' | 'paywalls' | 'checkouts', id: string): Promise<import("./types.js").TestPaymentResource>;
+    updateTestPayment(kind: 'wallets' | 'paywalls' | 'checkouts', id: string, input: Partial<import('./types.js').TestWalletInput | import('./types.js').TestPaywallInput | import('./types.js').TestCheckoutInput>): Promise<import("./types.js").TestPaymentResource>;
+    deleteTestPayment(kind: 'wallets' | 'paywalls' | 'checkouts', id: string): Promise<void>;
+    walletBalance(id: string): Promise<import("./types.js").TestPaymentResource>;
+    topUpTestWallet(id: string, amount: number): Promise<{
+        testMode: true;
+        balance: number;
+        transaction: import('./types.js').TestTransaction;
+    }>;
+    walletPay(id: string, input: import('./types.js').TestPaymentInput): Promise<import("./types.js").TestPaymentResult>;
+    listWalletTransactions(id: string, options?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        testMode: true;
+        transactions: import('./types.js').TestTransaction[];
+        nextCursor?: string;
+    }>;
+    completeTestCheckout(id: string, input: {
+        idempotencyKey: string;
+        card: {
+            number: string;
+            expiry?: string;
+            cvc?: string;
+        };
+    }): Promise<import("./types.js").TestCheckoutAttempt>;
+    confirmTestCheckout(id: string, confirmationToken: string): Promise<import("./types.js").TestCheckoutAttempt>;
+    saveCredential(input: import('./types.js').CredentialInput): Promise<{
+        credential: import('./types.js').Credential;
+        password?: string;
+    }>;
+    credentials(): Promise<{
+        credentials: import('./types.js').Credential[];
+        limit: number;
+    }>;
+    credential(id: string): Promise<import("./types.js").Credential>;
+    updateCredential(id: string, input: Partial<import('./types.js').CredentialInput>): Promise<import("./types.js").Credential>;
+    deleteCredential(id: string): Promise<void>;
+    revealCredential(id: string, approvalId?: string): Promise<import("./types.js").CredentialReveal>;
+    generatePassword(length?: number): Promise<{
+        password: string;
+    }>;
     createEmailInbox(settings?: import('./types.js').EmailInboxSettings): Promise<EmailInbox>;
     emailInboxes(): Promise<{
         inboxes: EmailInbox[];
@@ -304,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;
     }
@@ -170,6 +174,71 @@ export class Kivel {
             throw new KivelError('Attachment link expired or unavailable.', response.status, response.headers.get('x-request-id') ?? undefined);
         return new Uint8Array(await response.arrayBuffer());
     }
+    createTestWallet(input) {
+        return this.request('POST', '/api/test-wallets', input);
+    }
+    createTestPaywall(input) {
+        return this.request('POST', '/api/test-paywalls', input);
+    }
+    createTestCheckout(input) {
+        return this.request('POST', '/api/test-checkouts', input);
+    }
+    testPayments(kind) {
+        return this.request('GET', `/api/test-${kind}`);
+    }
+    testPayment(kind, id) {
+        return this.request('GET', `/api/test-${kind}/${encodeURIComponent(id)}`);
+    }
+    updateTestPayment(kind, id, input) {
+        return this.request('PATCH', `/api/test-${kind}/${encodeURIComponent(id)}`, input);
+    }
+    deleteTestPayment(kind, id) {
+        return this.request('DELETE', `/api/test-${kind}/${encodeURIComponent(id)}`);
+    }
+    walletBalance(id) {
+        return this.testPayment('wallets', id);
+    }
+    topUpTestWallet(id, amount) {
+        return this.request('POST', `/api/test-wallets/${encodeURIComponent(id)}/top-up`, { amount });
+    }
+    walletPay(id, input) {
+        return this.request('POST', `/api/test-wallets/${encodeURIComponent(id)}/pay`, input);
+    }
+    listWalletTransactions(id, options = {}) {
+        const query = new URLSearchParams();
+        if (options.cursor)
+            query.set('cursor', options.cursor);
+        if (options.limit !== undefined)
+            query.set('limit', String(options.limit));
+        return this.request('GET', `/api/test-wallets/${encodeURIComponent(id)}/transactions?${query}`);
+    }
+    completeTestCheckout(id, input) {
+        return this.request('POST', `/api/test-checkouts/${encodeURIComponent(id)}/complete`, input);
+    }
+    confirmTestCheckout(id, confirmationToken) {
+        return this.request('POST', `/api/test-checkouts/${encodeURIComponent(id)}/confirm`, { confirmationToken });
+    }
+    saveCredential(input) {
+        return this.request('POST', '/api/credentials', input);
+    }
+    credentials() {
+        return this.request('GET', '/api/credentials');
+    }
+    credential(id) {
+        return this.request('GET', `/api/credentials/${encodeURIComponent(id)}`);
+    }
+    updateCredential(id, input) {
+        return this.request('PATCH', `/api/credentials/${encodeURIComponent(id)}`, input);
+    }
+    deleteCredential(id) {
+        return this.request('DELETE', `/api/credentials/${encodeURIComponent(id)}`);
+    }
+    revealCredential(id, approvalId) {
+        return this.request('POST', `/api/credentials/${encodeURIComponent(id)}/reveal`, approvalId ? { approvalId } : {});
+    }
+    generatePassword(length = 24) {
+        return this.request('POST', '/api/passwords/generate', { length });
+    }
     createEmailInbox(settings = {}) {
         return this.request('POST', '/api/email-inboxes', settings);
     }

package/dist/types.d.ts

@@ -274,3 +274,158 @@ export interface OAuthProvider {
 export interface CreatedOAuthProvider extends OAuthProvider {
     client_secret: string;
 }
+export interface Credential {
+    id: string;
+    name: string;
+    url: string;
+    username: string;
+    agentMayRead: boolean;
+    authenticatorId?: string;
+    inboxId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CredentialInput {
+    name: string;
+    url: string;
+    username: string;
+    password?: string;
+    passwordLength?: number;
+    notes?: string;
+    agentMayRead?: boolean;
+    authenticatorId?: string | null;
+    inboxId?: string | null;
+}
+export type CredentialReveal = {
+    status: 'awaitingApproval';
+    approvalId: string;
+    answerUrl: string;
+} | {
+    status: 'revealed';
+    id: string;
+    password: string;
+    notes: string;
+};
+export type TestPaymentKind = 'wallet' | 'paywall' | 'checkout';
+export type CheckoutOutcome = 'succeeded' | 'declined' | 'insufficient_funds' | 'requires_verification' | 'expired';
+export interface TestTransaction {
+    id: string;
+    at: string;
+    kind: 'payment' | 'topup';
+    amount: number;
+    payee: string;
+    memo: string;
+    status: 'awaitingApproval' | 'authorized' | 'succeeded' | 'refused' | 'expired';
+    reason?: string;
+    approvalId?: string;
+    events: {
+        at: string;
+        status: string;
+        reason?: string;
+    }[];
+}
+export interface TestPaymentResource {
+    id: string;
+    kind: TestPaymentKind;
+    testMode: true;
+    name: string;
+    expiresAt: string;
+    endpointUrl?: string;
+    balance?: number;
+    availableBalance?: number;
+    reservedBalance?: number;
+    perPaymentLimit?: number;
+    dailyLimit?: number;
+    approvalThreshold?: number;
+    amount?: number;
+    currency?: string;
+    item?: string;
+    description?: string;
+    modes?: ('wallet' | 'permissive')[];
+    response?: {
+        status: number;
+        body: unknown;
+    };
+    successUrl?: string;
+    cancelUrl?: string;
+    webhookUrl?: string;
+    attempts?: {
+        id: string;
+        at: string;
+        outcome: CheckoutOutcome;
+        last4?: string;
+        verified?: boolean;
+    }[];
+    deliveries?: {
+        requestId: string;
+        at: string;
+        attempts: number;
+        status?: number;
+        error?: string;
+    }[];
+}
+export interface TestWalletInput {
+    name: string;
+    balance?: number;
+    availableBalance?: number;
+    reservedBalance?: number;
+    ttlSeconds?: number;
+    persistent?: boolean;
+    /** Only an owner/admin browser session can set spending controls. Agent keys omit them. */
+    perPaymentLimit?: number;
+    dailyLimit?: number;
+    approvalThreshold?: number;
+}
+export interface TestPaywallInput {
+    name: string;
+    amount: number;
+    description?: string;
+    modes?: ('wallet' | 'permissive')[];
+    response?: {
+        status: number;
+        body: unknown;
+    };
+    ttlSeconds?: number;
+    persistent?: boolean;
+}
+export interface TestCheckoutInput {
+    name: string;
+    item: string;
+    description?: string;
+    amount: number;
+    currency?: 'USD' | 'EUR' | 'GBP' | 'CAD' | 'AUD';
+    successUrl?: string;
+    cancelUrl?: string;
+    webhookUrl?: string;
+    ttlSeconds?: number;
+    persistent?: boolean;
+}
+export interface TestPaymentInput {
+    payee: string;
+    amount?: number;
+    memo?: string;
+    idempotencyKey: string;
+    authorizeOnly?: boolean;
+}
+export interface TestPaymentResult {
+    testMode: true;
+    status: 'awaitingApproval' | 'authorized' | 'succeeded';
+    transaction?: TestTransaction;
+    transactionId?: string;
+    approvalId?: string;
+    answerUrl?: string;
+    paymentHeader?: string;
+    headerName?: 'X-PAYMENT';
+    expiresAt?: string;
+    content?: unknown;
+    checkout?: TestCheckoutAttempt;
+}
+export interface TestCheckoutAttempt {
+    testMode: true;
+    id: string;
+    at: string;
+    outcome: CheckoutOutcome;
+    last4?: string;
+    verified?: boolean;
+    confirmationToken?: string;
+}

package/package.json

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