@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

npm install @pinset/substances

Usage

Basic Usage

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.

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+)

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+)

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:

{
  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:

// 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