@nextplus/js-sdk 0.0.1 → 0.0.4

package/README.md

@@ -0,0 +1,228 @@
+# @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.