@nextplus/js-sdk/README.md

A TypeScript SDK for interacting with the NextPlus API, automatically generated from OpenAPI specifications.

# @nextplus/js-sdk

A TypeScript SDK for interacting with the NextPlus API, automatically generated from OpenAPI specifications.

## Installation

```bash
npm install @nextplus/js-sdk
```

## Usage

### Basic Configuration

```typescript
import { configure } from '@nextplus/js-sdk';

// Configure with email authentication
const sdk = configure({
  baseURL: 'https://your-nextplus-instance.com/api',
  email: 'your-email@example.com',
  password: 'your-password',
  returnType: 'data', // 'data' | 'raw'
});

// Or configure with username authentication
const sdk = configure({
  baseURL: 'https://your-nextplus-instance.com/api',
  username: 'your-username',
  password: 'your-password',
  returnType: 'data',
});
```

### Return Types

- **`'data'`**: Returns only the response data (default behavior)
- **`'raw'`**: Returns the full response object with `{ data, request, response }`

### API Usage Examples

```typescript
// Find tables with filters
const tables = await sdk.TableService.find({
  filter: {
    name: {
      eq: 'my-table'
    }
  }
});

// Create a new table
const newTable = await sdk.TableService.create({
  body: {
    name: 'New Table',
    // ... other table properties
  }
});

// With raw response type
const sdk = configure({
  baseURL: 'https://api.example.com',
  email: 'user@example.com',
  password: 'password',
  returnType: 'raw'
});

const response = await sdk.TableService.find({});
console.log(response.data);      // Response data
console.log(response.request);   // Request object
console.log(response.response);  // Full HTTP response
```

## Development

### Prerequisites

- Node.js (v18 or higher)
- npm

### Setup

```bash
# Install dependencies
npm install

# Generate SDK from OpenAPI spec and build
npm run generate
```

### Available Scripts

- **`npm run generate`**: Clean, generate from OpenAPI spec, and build
- **`npm run build`**: Build TypeScript to JavaScript with type declarations
- **`npm run clean`**: Remove the `dist` folder
- **`npm run openapi-ts`**: Generate SDK from OpenAPI specification
- **`npm run lint`**: Run ESLint

### Development Workflow

1. **Make changes** to the source code in `src/`
2. **Generate and build**: `npm run generate`
3. **Test changes**: `npm run test` (run smoke tests)
4. **Publish**: `npm publish` (see Publishing section)

### Code Generation

The SDK is automatically generated from OpenAPI specifications using `@hey-api/openapi-ts`. The generated code includes:

- Type-safe API clients
- Request/response type definitions
- Authentication handling
- Error handling

Generated files are located in `src/sdk/` and should not be manually edited.

## Testing

### Smoke Tests

Run the smoke test to verify the SDK works correctly:

```bash
# Make sure your NextPlus instance is running on localhost:3000
npm run test
```

The smoke test (`src/smoke.ts`) demonstrates:
- Email and username authentication
- Different return types (`data` vs `raw`)
- API calls to the TableService
- Error handling

### Manual Testing

```typescript
// Create a test file
import { configure } from '@nextplus/js-sdk';

const sdk = configure({
  baseURL: 'http://localhost:3000/api',
  email: 'test@example.com',
  password: 'password',
});

// Test your API calls
const result = await sdk.TableService.find({});
console.log(result);
```

## Publishing

### Version Management

Update the version in `package.json` and publish:

```bash
# Bump version (patch, minor, or major)
npm version patch   # 0.0.3 -> 0.0.4
npm version minor   # 0.0.3 -> 0.1.0
npm version major   # 0.0.3 -> 1.0.0

# Publish to npm
npm publish
```

The `prepublishOnly` script automatically cleans and builds before publishing.

### Publishing Steps

1. **Ensure you're logged in**: `npm whoami`
2. **Build**: `npm run build` (optional, done automatically)
3. **Publish**: `npm publish`

## Project Structure

```
├── src/
│   ├── index.ts           # Main SDK entry point
│   ├── smoke.ts           # Smoke test file
│   └── sdk/               # Generated SDK code (do not edit)
│       ├── client/        # API client implementations
│       ├── core/          # Core utilities and types
│       └── *.gen.ts       # Generated files
├── dist/                  # Built JavaScript and declarations
├── package.json
├── tsconfig.json
└── README.md
```

## Configuration

### OpenAPI Generation

Configure OpenAPI generation in `openapi-ts.config.ts`:

```typescript
export default {
  input: 'path/to/openapi.json',
  output: './src/sdk',
  // ... other options
};
```

### TypeScript

The project uses modern TypeScript with:
- ES2020 target
- ESNext modules
- Strict type checking
- Declaration file generation

## License

MIT

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `npm run test`
5. Build: `npm run build`
6. Submit a pull request

## Support

For issues and questions, please create an issue in the repository or contact the NextPlus team.