@simplyhomes/sos-sdk/README.md

TypeScript SDK for Simply Homes SoS API v4

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

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

### For External Projects

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

## Usage

```typescript
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

```typescript
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)**
```bash
# 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**
```bash
# From root directory
pnpm gen:openapi

# This creates: server/openapi.json
```

### 2. Generate SDK

```bash
# 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!

```typescript
// 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/sos-sdk@2.x.x`, replacing the deprecated v1.x versions built with a different stack.

### Quick Publish (Recommended)

From the **root directory**:

```bash
# 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:**
```bash
# 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:**
```bash
# 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:

```bash
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

```typescript
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:

```bash
cd sos-sdk
pnpm gen:build
```

### "openapi.json not found"

Update the OpenAPI spec from your running server:

```bash
# 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:

```bash
# 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