# NetSuite Configuration Guide

## Overview

This document explains the configuration options for NetSuite API integration, including SuiteQL limits and REST API fallback options.

## Environment Variables

### SuiteQL Offset Validation

```bash
# For accounts WITHOUT SuiteAnalytics Connect (default)
NETSUITE_SKIP_OFFSET_VALIDATION=false

# For accounts WITH SuiteAnalytics Connect
NETSUITE_SKIP_OFFSET_VALIDATION=true
```

**Default**: `false`

**Purpose**: Controls whether the system enforces NetSuite's 99,000 record limit.

**Behavior**:
- `false` (default): System stops at 99,000 records and marks record type as complete
- `true`: System bypasses the limit and processes all available records

### REST API Fallback (Future Enhancement)

```bash
# Enable REST API fallback preparation
NETSUITE_ENABLE_REST_API_FALLBACK=true

# Disable REST API fallback (default)
NETSUITE_ENABLE_REST_API_FALLBACK=false
```

**Default**: `false`

**Purpose**: Prepares the system for future REST API integration when SuiteQL limits are reached.

### SuiteQL Limits

```bash
# Maximum offset for SuiteQL queries
NETSUITE_SUITEQL_MAX_OFFSET=99000

# Maximum batch size for SuiteQL queries
NETSUITE_SUITEQL_MAX_BATCH_SIZE=1000

# Default concurrency limit per tenant
NETSUITE_DEFAULT_CONCURRENCY_LIMIT=5
```

## NetSuite Account Types

### Accounts WITHOUT SuiteAnalytics Connect

- **Limit**: 99,000 records (100 batches of 1,000)
- **Behavior**: System gracefully stops at limit and marks as complete
- **Configuration**: `NETSUITE_SKIP_OFFSET_VALIDATION=false`

### Accounts WITH SuiteAnalytics Connect

- **Limit**: No practical limit (millions of records)
- **Behavior**: System processes all available records
- **Configuration**: `NETSUITE_SKIP_OFFSET_VALIDATION=true`

## Future Enhancements

### REST API Integration

When SuiteQL limits are reached for accounts without SuiteAnalytics Connect, the system will:

1. Use REST API endpoints to retrieve additional records
2. Seamlessly continue processing beyond the 99,000 limit
3. Maintain the same data consistency and error handling

### Configuration for REST API

```bash
# Enable REST API integration
NETSUITE_REST_API_ENABLED=true

# REST API base URL
NETSUITE_REST_API_BASE_URL=https://{account}.restlets.api.netsuite.com

# REST API timeout
NETSUITE_REST_API_TIMEOUT=30

# REST API retry attempts
NETSUITE_REST_API_RETRY_ATTEMPTS=3
```

## Migration Path

### Current State
- System respects 99,000 record limit for accounts without SuiteAnalytics Connect
- Graceful handling prevents import failures
- Clear logging indicates when limits are reached

### Future State
- REST API integration for accounts without SuiteAnalytics Connect
- Seamless processing beyond 99,000 record limit
- Hybrid approach: SuiteQL for initial data, REST API for overflow

## Troubleshooting

### Import Stops at 99,000 Records

**Symptom**: Import completes successfully but only processes 99,000 records

**Cause**: NetSuite account doesn't have SuiteAnalytics Connect add-on

**Solution**:
1. Upgrade NetSuite account to include SuiteAnalytics Connect, OR
2. Accept the limitation and process data in chunks, OR
3. Wait for REST API integration to be implemented

### Configuration Not Working

**Symptom**: System still enforces limits even with `NETSUITE_SKIP_OFFSET_VALIDATION=true`

**Cause**: Configuration not loaded or cache not cleared

**Solution**:
1. Clear Laravel configuration cache: `php artisan config:clear`
2. Restart queue workers
3. Verify environment variable is set correctly

## Best Practices

1. **Start with defaults**: Use `NETSUITE_SKIP_OFFSET_VALIDATION=false` initially
2. **Monitor logs**: Check for messages about reaching record limits
3. **Plan for growth**: Consider SuiteAnalytics Connect for large datasets
4. **Test configurations**: Verify behavior in non-production environments first