@kivel.io/sdk 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @kivel.io/sdk
 
+## 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

@@ -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

@@ -123,6 +123,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[];

package/dist/index.js

@@ -170,6 +170,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.8.0",
   "type": "module",
   "exports": {
     ".": {