@simplyhomes/sos-sdk

TypeScript SDK for Simply Homes SoS API v4, generated from OpenAPI specification.

Features

• Type-safe: Full TypeScript support with auto-generated types
• Workspace linked: Instant updates during local development (no npm install needed)
• Hierarchical API: Organized resource structure matching Stainless SDK pattern
• Zero cost: Free alternative to paid SDK generation services

Installation

For Local Development (This Monorepo)

The SDK is automatically available via workspace linking. No installation needed!

# SDK is already linked in client/package.json as workspace:*

For External Projects

npm install @simplyhomes/sos-sdk
# or
pnpm add @simplyhomes/sos-sdk

Usage

import SimplyHomesSDK from '@simplyhomes/sos-sdk';

// Initialize the SDK
const sdk = new SimplyHomesSDK({
  environment: 'production', // 'local' | 'staging' | 'production'
  authToken: 'Bearer your-token-here',
  organizationId: 'your-org-id', // optional
  apiKey: 'your-api-key', // optional
});

// Use the SDK
const transactions = await sdk.v4.transactions.list.all();
const transaction = await sdk.v4.transactions.list.one('trans-123');
const viewTransactions = await sdk.v4.transactions.list.withView('view-456');

// Create a transaction
const newTransaction = await sdk.v4.transactions.create.one({
  propertyId: 'prop-123',
  status: 'pending',
  contractPrice: 350000,
});

// Update a transaction
await sdk.v4.transactions.update.one('trans-123', {
  status: 'closed',
});

Type Imports

import type SimplyHomesSDK from '@simplyhomes/sos-sdk';

// Access entity types via namespace
type Transaction = SimplyHomesSDK.V4.SosTransactionEntity;
type Property = SimplyHomesSDK.V4.SosPropertyEntity;

Development Workflow

1. Update OpenAPI Spec (When API Changes)

When you make changes to the backend API, update the OpenAPI spec:

Option A: Copy from Running Server (Recommended)

# 1. Start the server
pnpm s:dev

# 2. Visit http://localhost:4000/api/v4-json in your browser
# 3. Copy the entire JSON response
# 4. Paste it into server/openapi.json

Option B: Generate via Script

# From root directory
pnpm gen:openapi

# This creates: server/openapi.json

2. Generate SDK

# From root directory
pnpm gen:sdk

# Or manually:
cd sos-sdk
pnpm gen:build

3. Use in Client

The client automatically sees updates via workspace linking!

// client/src/hooks/sdk/useSoS_SDK.ts
import SimplyHomesSDK from '@simplyhomes/sos-sdk';

export const useSoS_SDK = () => {
  const { sosAccessToken } = useStoreApp(['sosAccessToken']);

  const sdk = useMemo(
    () =>
      new SimplyHomesSDK({
        environment: import.meta.env.VITE_MODE === 'development' ? 'local' : import.meta.env.VITE_MODE,
        authToken: `Bearer ${sosAccessToken}`,
      }),
    [sosAccessToken],
  );

  return sdk;
};

SDK Structure

sdk.v4.{resource}.{operation}.{method}()

Resources: transactions, properties, units, options, views, etc.

Operations:

• list: Read operations (all, one, withView, withFilters, etc.)
• create: Create operations
• update: Update operations
• delete: Delete operations

Example Methods:

• sdk.v4.transactions.list.all() - Get all transactions
• sdk.v4.transactions.list.one(id) - Get one transaction
• sdk.v4.transactions.list.withView(viewId) - Get with view
• sdk.v4.transactions.create.one(body) - Create transaction
• sdk.v4.transactions.update.one(id, body) - Update transaction
• sdk.v4.transactions.delete.one(id) - Delete transaction

Publishing to npm

Version 2.0.0+: This SDK is published to npm as @simplyhomes/[email protected], replacing the deprecated v1.x versions built with a different stack.

Quick Publish (Recommended)

From the root directory:

# Auto-increments patch version and publishes
# Example: 2.0.0 → 2.0.1 → 2.0.2
pnpm sdk:publish

This command will:

1. Auto-increment patch version (e.g., 2.0.5 → 2.0.6)
2. Generate latest SDK from OpenAPI spec
3. Build TypeScript
4. Publish to npm registry

First-Time Setup

Prerequisites:

# 1. Ensure you're logged into npm
npm whoami
# Should display your npm username

# 2. Verify @simplyhomes organization access
npm org ls simplyhomes
# Should list you as a member

First Publish:

# 1. Generate SDK (first time)
pnpm sdk:gen

# 2. Commit generated files (first time only)
cd sos-sdk
git add src/generated/
git commit -m "chore: commit generated SDK files for npm publishing"
git push

# 3. Publish v2.0.0
cd ..
pnpm sdk:publish

Manual Publishing (Alternative)

From the sos-sdk directory:

cd sos-sdk

# Auto-increment and publish
pnpm publish

# Or step-by-step:
pnpm gen          # Generate from OpenAPI
pnpm build        # Compile TypeScript
npm publish       # Publish (no auto-increment)

Scripts

SDK Package (sos-sdk/)

• pnpm gen - Generate SDK from OpenAPI spec
• pnpm build - Compile TypeScript to dist/
• pnpm publish - Auto-increment version + generate + build + publish

Root Package

• pnpm sdk:gen - Generate and build SDK
• pnpm sdk:publish - Publish SDK to npm (auto-increments patch version)

Configuration

ClientOptions

interface ClientOptions {
  apiKey?: string | null; // x-api-key header
  organizationId?: string | null; // organization-id header
  authToken?: string | null; // Authorization header
  environment?: 'local' | 'staging' | 'production';
  baseURL?: string; // Custom base URL (overrides environment)
  timeout?: number; // Request timeout (ms)
  maxRetries?: number; // Max retry attempts
  fetch?: typeof fetch; // Custom fetch implementation
}

Environments

• local: http://localhost:4000
• staging: https://sos-api.simplyhomes.dev
• production: https://sos-api.simplyhomes.com

Troubleshooting

"Cannot find module './generated'"

You need to generate the SDK first:

cd sos-sdk
pnpm gen:build

"openapi.json not found"

Update the OpenAPI spec from your running server:

# Option 1: Copy manually (recommended)
# 1. Visit http://localhost:4000/api/v4-json
# 2. Copy JSON and paste into server/openapi.json

# Option 2: Generate via script
cd server
pnpm gen:openapi

OpenAPI Validation Errors

The SDK generator has validation skip enabled (skipValidateSpec: true) to handle minor differences between NestJS Swagger's OpenAPI 3.1.0 output and OpenAPI Generator's expectations. This is safe and allows SDK generation to succeed even with minor spec variations.

If you want stricter validation:

1. Edit sos-sdk/openapi-config.yaml
2. Remove or set skipValidateSpec: "false"
3. Fix any validation errors in the OpenAPI spec

Workspace link not working

Reinstall dependencies:

# From root
pnpm install

Contributing

When adding new resources or updating existing ones:

1. Update backend controllers/DTOs
2. Update OpenAPI spec:
   • Recommended: Copy from http://localhost:4000/api/v4-json → paste into server/openapi.json
   • Alternative: Run pnpm gen:openapi from server directory
3. Create resource wrapper in src/resources/{resource}.ts (follow transactions.ts pattern)
4. Add resource to src/resources/v4.ts
5. Regenerate SDK: pnpm gen:sdk from root directory

License

UNLICENSED - Internal use only