# PandaDB Node.js SDK - Development Guide

This guide explains how to build and publish the PandaDB Node.js SDK.

## Development Setup

1. Clone the repository:
```bash
git clone <your-repo-url>
cd sdk
```

2. Install dependencies:
```bash
npm install
```

## Building the SDK

1. Run the build command:
```bash
npm run build
```

This will:
- Clean the dist directory
- Compile TypeScript to JavaScript
- Generate type declaration files
- Create source maps

The build output will be in the `dist` directory:
- `dist/*.js` - Compiled JavaScript files
- `dist/*.d.ts` - TypeScript declaration files
- `dist/*.map` - Source maps

## Testing

1. Run tests:
```bash
npm test
```

2. Run linting:
```bash
npm run lint
```

3. Format code:
```bash
npm run format
```

## Publishing to npm

1. Login to npm:
```bash
npm login
```

2. Update version (choose one):
```bash
npm version patch  # For bug fixes (0.0.x)
npm version minor  # For new features (0.x.0)
npm version major  # For breaking changes (x.0.0)
```

3. Build and publish:
```bash
npm run build
npm publish
```

The package will be published as `@pandadb/node`.

## Development Workflow

1. Make changes to files in `src/`
2. Run tests: `npm test`
3. Run linting: `npm run lint`
4. Build: `npm run build`
5. Test the built package:
   ```bash
   # In another project
   npm install ../path/to/sdk
   ```

## Package Structure

```
sdk/
├── src/
│   ├── client.ts      # Main SDK implementation
│   ├── types.ts       # TypeScript type definitions
│   ├── errors.ts      # Error handling classes
│   └── index.ts       # Public API exports
├── package.json       # Package configuration
└── tsconfig.json      # TypeScript configuration
```

## Local Testing

To test the SDK locally in another project:

1. In the SDK directory:
```bash
npm run build
npm pack
```

2. In your test project:
```bash
npm install ../path/to/pandadb-node-0.1.0.tgz
```

## Continuous Integration

Before publishing:
1. Ensure all tests pass
2. Check linting
3. Verify the build works
4. Test the package locally

## Publishing Checklist

- [ ] Update version in package.json
- [ ] Run tests
- [ ] Run linting
- [ ] Build the package
- [ ] Test the built package locally
- [ ] Update README if needed
- [ ] Commit all changes
- [ ] Create git tag
- [ ] Push to repository
- [ ] Publish to npm

## Example Usage

After publishing, users can install the package:

```bash
npm install @pandadb/node
```

And use it in their code:

```typescript
import { PandaDB } from '@pandadb/node';

const client = new PandaDB({
  token: 'YOUR_AUTH_TOKEN'
});

// Execute a query
const result = await client.query(
  'db_123abc',
  'SELECT * FROM users WHERE age > ?',
  [18]
);

// Use real-time subscriptions
const unsubscribe = client.subscribe(
  'db_123abc',
  'users',
  {
    onCreate: (user) => console.log('New user:', user),
    onUpdate: (user) => console.log('Updated user:', user),
    onDelete: (id) => console.log('Deleted user:', id)
  }
);

// Clean up when done
unsubscribe();
```

## Troubleshooting

Common issues:

1. Build errors:
   - Run `npm install` to ensure all dependencies are installed
   - Check TypeScript errors in your IDE
   - Run `npm run lint` to find issues

2. Publishing errors:
   - Ensure you're logged in to npm: `npm login`
   - Check if the package name is available
   - Verify you have publish access to the @pandadb organization

3. Type errors:
   - Check that all types are properly exported in index.ts
   - Verify tsconfig.json settings
   - Ensure declaration files are generated

## Support

For any issues:
1. Check the troubleshooting guide
2. Run tests and linting
3. Contact the PandaDB team