TypeScript SDK

Installation

npm install @soft-house/sdk

Requirements: Node.js 18+, TypeScript 5.0+ (recommended)

Quick Start

import { SoftHouse } from '@soft-house/sdk';

const soft = new SoftHouse({
  apiKey: process.env.SOFT_HOUSE_API_KEY!,
});

// Create a wish
const wish = await soft.wishes.create({
  query: 'Find me a laptop under $1500',
  budget: { max: 1500, currency: 'USD' },
});

console.log(wish.id, wish.status);

Configuration

const soft = new SoftHouse({
  apiKey: 'sk_live_...',
  baseUrl: 'https://api.soft.house',  // default
  timeout: 30000,                      // 30s default
  retry: {
    maxRetries: 3,                     // auto-retry on 5xx and 429
    initialDelay: 1000,                // exponential backoff
  },
});

// Browser usage with session cookies
const browserClient = SoftHouse.withCredentials();

// Backend usage with API key
const serverClient = SoftHouse.withApiKey(process.env.SOFT_HOUSE_API_KEY!);

Resources

Wishes

// Create
const wish = await soft.wishes.create({ query: '...' });

// List
const { wishes, total } = await soft.wishes.list({ status: 'active', limit: 10 });

// Get
const wish = await soft.wishes.get('wish_abc123');

// Update
const updated = await soft.wishes.update('wish_abc123', { status: 'cancelled' });

// Delete
await soft.wishes.delete('wish_abc123');

Mandates

// Create AP2 mandate
const mandate = await soft.mandates.create({
  type: 'intent',
  protocol_type: 'ap2',
  max_amount: 1500,
});

// Verify signature
const { valid } = await soft.mandates.verify(mandate.id);

// List
const { mandates } = await soft.mandates.list({ protocol_type: 'ap2' });

// Revoke
await soft.mandates.revoke(mandate.id);

Payments

// Process payment (idempotency key required)
const payment = await soft.payments.create({
  mandate_id: 'mnd_abc123',
  amount: 119999,
  idempotency_key: 'pay_unique_456',
});

// List payments
const { payments } = await soft.payments.list({ status: 'succeeded' });

// Refund
await soft.payments.refund(payment.id);

Error Handling

import { SoftHouseError, RateLimitError } from '@soft-house/sdk';

try {
  const wish = await soft.wishes.create({ query: '...' });
} catch (err) {
  if (err instanceof RateLimitError) {
    // Automatic retry is built in, but you can handle it manually
    console.log(`Retry after ${err.retryAfter}ms`);
  } else if (err instanceof SoftHouseError) {
    console.error(err.code);      // 'INVALID_INPUT'
    console.error(err.message);   // Human-readable message
    console.error(err.status);    // HTTP status code
    console.error(err.requestId); // For support
  }
}

TypeScript Support

Full type definitions are included:

import type { Wish, Mandate, Payment, WishCreateParams } from '@soft-house/sdk';

const params: WishCreateParams = {
  query: 'Find me headphones',
  budget: { max: 200, currency: 'USD' },
};

const wish: Wish = await soft.wishes.create(params);