npm package: @pinset/substances
Description: Therapeutic substance profiles for the Pinset platform
Author: Pinset Platform
Latest version: 0.2.0

# @pinset/substances

Therapeutic substance profiles for the Pinset platform.

**Version 0.2.0** introduces critical safety features including substance variants, structured contraindications, and comprehensive harm reduction guidance.

## Installation

```bash
npm install @pinset/substances
```

## Usage

### Basic Usage

```typescript
import { psilocybin, lsd, mdma, ketamine } from '@pinset/substances'
import { allSubstances, getSubstanceById, getSubstancesByClass } from '@pinset/substances'
import type { Substance, SubstanceClass } from '@pinset/substances'

// Access individual substances
console.log(psilocybin.dosing)
console.log(lsd.tolerance.crossTolerance)

// Get all substances
const substances = allSubstances

// Get by ID
const substance = getSubstanceById('psilocybin')

// Get by class
const tryptamines = getSubstancesByClass('tryptamine')
```

### Working with Variants (v0.2.0+)

**SAFETY CRITICAL**: Different species and strains can have vastly different potencies. Always check variant-specific dosing.

```typescript
import { psilocybin } from '@pinset/substances'

// Find the variant you're working with
const cubensis = psilocybin.variants?.find(v => v.id === 'psilocybe-cubensis')
const azurescens = psilocybin.variants?.find(v => v.id === 'psilocybe-azurescens')

// Check dosing - azurescens is ~3x more potent!
console.log(cubensis?.dosing.common)    // 1.5-3.5g
console.log(azurescens?.dosing.common)  // 0.5-1.2g  ⚠️ Much lower!

// Check strain-specific potency modifiers
const penisEnvy = cubensis?.strains?.find(s => s.name === 'Penis Envy')
console.log(penisEnvy?.potencyModifier)  // 2.0 - reduce dose by 50%!
```

### Using Structured Safety Data (v0.2.0+)

```typescript
import { mdma } from '@pinset/substances'

// Check structured contraindications with severity levels
const maoi = mdma.structuredContraindications?.find(c => c.id === 'ci-maoi')
console.log(maoi?.severity)        // 'danger'
console.log(maoi?.recommendation)  // 'Absolute contraindication. Never combine...'

// Access comprehensive harm reduction guidance
console.log(mdma.safety?.harmReduction)
// ['Test substance with reagent kit...', 'Wait 3 months between uses...']

// Get emergency guidance
console.log(mdma.safety?.emergencyGuidance)
// 'For medical emergency (hyperthermia, chest pain...): Call 911...'

// Check interaction wait times
const ssri = mdma.interactions.find(i => i.substance === 'SSRIs / SNRIs')
console.log(ssri?.waitTime)  // 336 hours (14 days)
```

### Chemistry and Toxicity Info (v0.2.0+)

```typescript
import { psilocybin } from '@pinset/substances'

// Access chemistry data
console.log(psilocybin.chemistry?.formula)           // 'C₁₂H₁₇N₂O₄P'
console.log(psilocybin.chemistry?.iupacName)         // IUPAC systematic name
console.log(psilocybin.chemistry?.molecularWeight)   // 284.25

// Check toxicity profile
console.log(psilocybin.toxicity?.ld50)
console.log(psilocybin.toxicity?.lethalDose)

// Legal status
console.log(psilocybin.legalStatus)
// 'Schedule I in United States; Schedule III in Canada...'
```

## What's Included

### Substances

Currently includes comprehensive profiles for:
- **Psilocybin** (tryptamine) - Classic psychedelic from magic mushrooms
- **LSD** (lysergamide) - Classic psychedelic
- **MDMA** (empathogen) - Empathogen with PTSD therapy applications
- **Ketamine** (dissociative) - Dissociative anesthetic with rapid antidepressant effects

Each substance profile includes:

**Core Data:**
- **Pharmacokinetics**: Onset, peak, duration, metabolism
- **Tolerance**: Mechanisms, cross-tolerance, recovery timelines
- **Receptor Profile**: Target receptors, neuroplasticity effects
- **Dosing**: Threshold, light, common, strong, and heavy dose ranges
- **Routes of Administration**: Multiple ROAs with bioavailability and timing
- **Therapeutic Uses**: Medical applications with evidence levels
- **History**: Discovery, traditional use, modern research

**NEW in v0.2.0 - Safety Enhancements:**
- **Variants**: Species, strains, preparations with specific dosing (⚠️ CRITICAL for psilocybin - 3x potency difference between species!)
- **Structured Contraindications**: Detailed warnings with severity levels and recommendations
- **SafetyProfile**: Harm reduction tips, warning signs, emergency guidance with crisis hotlines
- **Chemistry**: IUPAC names, molecular formulas, CAS numbers
- **Toxicity**: LD50, lethal dose estimates, overdose symptoms
- **Interaction Wait Times**: Hours to wait after discontinuing interacting substances
- **Legal Status**: Current legal classification

### Types

All TypeScript interfaces are exported for type safety:

**Core Types:**
- `Substance` - Main substance interface
- `Pharmacokinetics`, `ToleranceProfile`, `ReceptorProfile`
- `DosingProfile`, `RouteOfAdministration`, `PhasedDuration`
- `TherapeuticUse`, `DrugInteraction`, `NeurotoxicityProfile`

**NEW in v0.2.0:**
- `SubstanceVariant` - Species, strains, isomers with different potencies
- `Contraindication` - Structured contraindication with severity and recommendations
- `SafetyProfile` - Comprehensive harm reduction and emergency guidance
- `ChemistryInfo` - Molecular and chemical data
- `ToxicityProfile` - LD50 and overdose information

## Variant System (v0.2.0)

### Why Variants Matter

Different forms of the same substance can have **dramatically different potencies**:

| Substance | Variant | Dosing | Potency Difference |
|-----------|---------|--------|-------------------|
| Psilocybin | P. cubensis | 1.5-3.5g | Baseline |
| Psilocybin | P. azurescens | 0.5-1.2g | **3x stronger** ⚠️ |
| Psilocybin | Synthetic | 10-25mg | Pure compound (different units!) |
| Ketamine | Racemic | 30-75mg | Baseline |
| Ketamine | Esketamine | 15-40mg | **2x stronger** ⚠️ |

**Without variant-specific dosing**, users could accidentally take dangerously high doses. The variant system prevents this harm.

### Variant Types

- **`species`**: Different biological species (e.g., P. cubensis vs P. azurescens)
- **`strain`**: Cultivated strains within a species (e.g., Golden Teacher vs Penis Envy)
- **`isomer`**: Different molecular isomers (e.g., racemic ketamine vs S-ketamine)
- **`preparation`**: Different forms or preparations (e.g., natural vs synthetic)

### Integration with Cultivation Data

Variants include optional `cultivationSpeciesId` and `cultivationStrainId` fields for integration with cultivation tracking systems like `@pinset/cultivation`:

```typescript
{
  id: 'psilocybe-cubensis',
  cultivationSpeciesId: 'species_psilocybe_cubensis',  // Links to grow data
  strains: [{
    name: 'Golden Teacher',
    potencyModifier: 1.0,
    cultivationStrainId: 'strain_gt'  // Links to specific strain grow data
  }]
}
```

## Harm Reduction Focus

All substance profiles are designed with harm reduction in mind:
- Evidence-based dosing recommendations
- **Variant-specific dosing for accurate harm reduction**
- Structured contraindications with severity levels
- Detailed drug interaction information with wait times
- Tolerance and spacing guidance
- Neurotoxicity risk profiles
- Emergency guidance with crisis hotline numbers (988, Fireside Project)
- Practical harm reduction tips (testing, temperature management, hydration, etc.)

## Migration Guide from v0.1.x

v0.2.0 is **backward compatible** with optional additions:

### Deprecated (still functional)
- `contraindications: string[]` - Use `structuredContraindications` instead
- `safetyNotes: string[]` - Use `safety.notes` instead

### New Optional Fields
All new fields are optional, so existing code continues to work:

```typescript
// v0.1.x - still works
const dose = psilocybin.dosing.common

// v0.2.0 - enhanced with variants
const cubensisDose = psilocybin.variants
  ?.find(v => v.id === 'psilocybe-cubensis')
  ?.dosing.common ?? psilocybin.dosing.common
```

## Data Accuracy

Substance data is compiled from:
- Peer-reviewed scientific literature
- Clinical trial data (MAPS, Johns Hopkins, Imperial College)
- FDA and regulatory agency guidelines
- Erowid and PsychonautWiki community databases
- Published alkaloid content studies (for variant potencies)
- Harm reduction organizations (DanceSafe, Zendo Project, Fireside Project)

## License

MIT