@studyportals/sp-hs-misc/CHANGELOG-v3.0.0.md

Miscellaneous code used in HouseStark's projects

# Changelog: @studyportals/sp-hs-misc v3.0.0 → v3.0.5

**Release Date:** December 15, 2025  
**Branch:** CITA-23301-Campaigns-table-revamp  
**Pull Request:** [#45](https://github.com/studyportals/hs-misc/pull/45)

---

## v3.0.5 (Patch) - Browser Build Restored

**BREAKING CHANGE for browser CDN consumers:** Browser imports now use ES modules instead of global scripts.

### Browser Build Restoration

The browser build (`bin-browser/`) has been **restored** as an ES2020 module build for direct browser usage via CDN (jsDelivr, unpkg, etc.).

**What changed:**
- ✅ `/bin/` - CommonJS for Node.js (unchanged)
- ✅ `/bin-browser/` - ES2020 modules for browsers (restored)

### Browser Usage

**For v3.0.0 - v3.0.4 (BROKEN):**
```html
<!-- These versions don't work in browsers via CDN -->
<script src="https://cdn.jsdelivr.net/npm/@studyportals/sp-hs-misc@3.0.4/bin/index.js"></script>
<!-- Error: exports is not defined -->
```

**For v3.0.5+ (WORKING - ES Modules):**
```html
<script type="module">
  import { ServiceLayerClient, BaseSuperAgentRequestFactory } from 'https://cdn.jsdelivr.net/npm/@studyportals/sp-hs-misc@3.0.5/bin-browser/index.js';
  
  const client = new ServiceLayerClient(
    new BaseSuperAgentRequestFactory(),
    'https://api.example.com',
    3
  );
</script>
```

**Direct class imports:**
```html
<script type="module">
  import { Dictionary } from 'https://cdn.jsdelivr.net/npm/@studyportals/sp-hs-misc@3.0.5/bin-browser/src/data-structures/dictionary.class.js';
  
  const myDict = new Dictionary();
</script>
```

### Migration from v2.x Browser Usage

**Before (v2.x - Global script):**
```html
<script src="https://cdn.jsdelivr.net/npm/@studyportals/sp-hs-misc@2.x/bin-browser/index.js"></script>
<script>
  // Classes available globally
  const client = new ServiceLayerClient(...);
</script>
```

**After (v3.0.5+ - ES Modules):**
```html
<script type="module">
  import { ServiceLayerClient } from 'https://cdn.jsdelivr.net/npm/@studyportals/sp-hs-misc@3.0.5/bin-browser/index.js';
  
  const client = new ServiceLayerClient(...);
</script>
```

**Key differences:**
- Must use `<script type="module">`
- Must use `import` statements
- No global namespace pollution
- Modern browsers only (ES2020+)

### Node.js Usage (Unchanged)

Node.js consumers are **not affected** by this change:

```typescript
// Still works exactly the same
import { ServiceLayerClient } from '@studyportals/sp-hs-misc';
const { Dictionary } = require('@studyportals/sp-hs-misc');
```

---

## v3.0.1 (Patch)

Added proper entry point to `package.json`:

```json
{
  "main": "bin/index.js",
  "types": "bin/index.d.ts"
}
```

This allows importing directly from the package name:

```typescript
import { ServiceLayerClient, Dictionary } from '@studyportals/sp-hs-misc';
```

---

## v3.0.0 (Major)

## Breaking Changes

### 1. Dependency Update: `@studyportals/sp-millennium-falcon` ^3.0.0

The package now requires `@studyportals/sp-millennium-falcon` version 3.0.0 or higher.

**Impact:**
- `CampaignDto` constructor signature changed (removed `externalNotes` parameter)
- `ICampaign` interface no longer includes `externalNotes` property
- `CampaignType` enum no longer includes `ADVANCED_NRBP` and `RBP_CPL` values

### 2. `ServiceLayerDataModelsFactory.createCampaign()` Changes

**Before (v2.x):**
```typescript
public createCampaign(serviceLayerData: {[key: string]: any}): ICampaign {
    // ...
    const externalNotes = serviceLayerData["external_notes"];
    return new CampaignDto(id, title, startDate, endDate, currency, budget, type, externalNotes);
}
```

**After (v3.0.0):**
```typescript
public createCampaign(serviceLayerData: {[key: string]: any}): ICampaign {
    // ...
    return new CampaignDto(id, title, startDate, endDate, currency, budget, type);
}
```

### 3. `translateCampaignType()` Changes

**Removed support for deprecated campaign types:**
- `advanced_nrbp` → Previously mapped to `CampaignType.ADVANCED_NRBP`
- `rbp_cpl` → Previously mapped to `CampaignType.RBP_CPL`

These values will now fall through to `CampaignType.UNKNOWN`.

### 4. Browser Build Removed (v3.0.0 - v3.0.4) — RESTORED in v3.0.5

The separate browser build (`bin-browser/`) was **removed in v3.0.0** but **restored in v3.0.5** as ES2020 modules.

**v3.0.0 - v3.0.4 status:**
- Browser build removed
- CDN imports broken
- Only CommonJS `/bin/` available

**v3.0.5+ status:**
- Browser build restored as ES2020 modules
- CDN imports work with `<script type="module">`
- See v3.0.5 changelog above for browser usage

**Before (v2.x):**
```typescript
// No main entry point — had to use direct paths
import { ServiceLayerClient } from '@studyportals/sp-hs-misc/bin-browser/src/adapters/service-layer-client.class';
import { Dictionary } from '@studyportals/sp-hs-misc/bin/src/data-structures/dictionary.class';
```

**After (v3.0.0+):**
```typescript
// Main entry point now works (RECOMMENDED for Node.js)
import { ServiceLayerClient, Dictionary } from '@studyportals/sp-hs-misc';

// Direct bin/ imports still work if needed
import { ServiceLayerClient } from '@studyportals/sp-hs-misc/bin/src/adapters/service-layer-client.class';

// For browsers via CDN (v3.0.5+)
// import { ServiceLayerClient } from 'https://cdn.jsdelivr.net/npm/@studyportals/sp-hs-misc@3.0.5/bin-browser/index.js';
```

**Action required for v3.0.0 - v3.0.4:**
- [ ] Search your codebase for `sp-hs-misc/bin-browser` — these will break
- [ ] Replace all direct path imports with the main entry point where possible
- [ ] Test that all imports resolve correctly

**Action required for v3.0.5+ browser users:**
- [ ] Update CDN URLs to v3.0.5+
- [ ] Add `type="module"` to script tags
- [ ] Use `import` statements instead of global variables

---

## Build System Modernization

### Removed Babel Dual Build

The package no longer produces a separate browser build. The babel tooling has been completely removed.

**Removed files:**
- `babel.js`
- `.babelrc`
- `.babelrc.browser.json`
- `tsconfig.node.json`

**Removed directories:**
- `bin-raw/`
- `bin-browser/`

**Removed npm scripts:**
- `build-node`
- `build-browser`
- `build-both`

**Removed devDependencies:**
- `@babel/cli`
- `@babel/core`
- `@babel/preset-env`
- `babel-plugin-transform-dir`

### TypeScript Configuration

**Updated `tsconfig.json`:**
- Target: `es2024`
- Module: `nodenext`
- Module Resolution: `nodenext`
- Output directory: `bin/` (single output)

### Test Framework

**Migrated from `mocha-typescript` to `@testdeck/mocha`:**
- `mocha-typescript` was incompatible with modern Node.js/ESM
- `@testdeck/mocha` provides the same decorator-based testing API

---

## Test Changes

### Removed Deprecated Test Cases

**File:** `tests-u/adapters/service-layer-data-models-factory.test.ts`

- Removed `translateCampaignType__ADVANCED_NRBP` test
- Removed `translateCampaignType__RBP_CPL` test
- Updated `createCampaignServiceLayerData()` helper to remove `external_notes` and add `type` field

### Removed Duplicate Test Directory

- Deleted `tests-u/adapters-tests/` (duplicate of `tests-u/adapters/`)

---

## Dependency Updates

| Package | Old Version | New Version |
|---------|-------------|-------------|
| `@studyportals/sp-millennium-falcon` | ^2.x | ^3.0.0 |
| `@testdeck/mocha` | - | 0.3.3 |
| `@types/js-cookie` | ^2.1.0 | ^3.0.6 |
| `@types/chai` | ^4.x | ^5.2.3 |
| `@types/mocha` | ^5.x | ^10.0.10 |
| `@types/node` | ^18.x | ^24.10.1 |
| `chai` | ^4.x | ^6.2.1 |
| `mocha` | ^6.x | ^11.7.5 |
| `nyc` | ^15.x | ^17.1.0 |
| `typescript` | ^4.x | ^5.9.3 |

**Removed devDependencies:**
- `mocha-typescript`
- `@babel/cli`
- `@babel/core`
- `@babel/preset-env`
- `babel-plugin-transform-dir`

---

## Engine Requirements

```json
{
  "engines": {
    "node": ">=24.0.0 <25.0.0",
    "npm": ">=11.0.0 <12.0.0"
  }
}
```

---

## Migration Guide for Consumers

### Step 1: Update millennium-falcon first

```bash
npm install @studyportals/sp-millennium-falcon@^3.0.0
```

### Step 2: Update hs-misc

```bash
npm install @studyportals/sp-hs-misc@^3.0.0
```

### Step 3: Remove deprecated code

1. **Remove references to `externalNotes`** on campaign objects
2. **Remove handling for deprecated campaign types:**
   - `CampaignType.ADVANCED_NRBP`
   - `CampaignType.RBP_CPL`

### Step 4: Update Node.js version

Ensure your environment runs Node.js 24.x.

---

## Files Changed

### Modified
- `package.json` - Version bump, dependency updates, script changes
- `tsconfig.json` - Modernized configuration
- `src/adapters/service-layer-data-models-factory.class.ts` - Removed external_notes, deprecated enum cases
- `tests-u/adapters/service-layer-data-models-factory.test.ts` - Updated test data, removed deprecated tests
- `index.ts` - No functional changes (imports remain same)

### Added
- `.github/copilot-instructions.md` - Comprehensive repository documentation

### Deleted
- `babel.js`
- `.babelrc`
- `.babelrc.browser.json`
- `tsconfig.node.json`
- `bin-raw/` (directory)
- `bin-browser/` (directory)
- `tests-u/adapters-tests/` (duplicate directory)

---

## Related Documentation

- [Campaigns Revamp Migration Plan](./Campaigns-Revamp-Migration-Plan.md) - Full migration guide for all dependent services
- [Copilot Instructions](./.github/copilot-instructions.md) - Repository documentation for AI assistants