CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Development Commands

Build and Development

npm run build            # Full build: clean dist, compile TypeScript, copy icons
npm run dev             # Watch mode for TypeScript compilation
npm run format          # Format code with Prettier
npm run lint            # Lint code with ESLint  
npm run lintfix         # Auto-fix ESLint issues
npm run prepublishOnly  # Pre-publish checks: build + strict lint

Testing

npm test                # Run unit tests
npm run test:watch      # Run tests in watch mode
npm run test:unit       # Run unit tests (explicit)
npm run test:unit:watch # Watch unit tests during development

Running Single Tests

npm test -- <test-file-name>           # Run specific test file
npm test -- --testNamePattern="<name>" # Run tests matching pattern

Architecture Overview

This is an n8n community node package that provides Substack API integration. The project follows n8n's node development patterns with a modular resource-based architecture.

Core Structure

Main Node:
```
nodes/Substack/Substack.node.ts
```
- Central node implementation that routes operations to resource handlers
Utility Layer:
```
SubstackUtils.ts
```
- Client initialization, caching, response validation, and error handling
Resource Modules: Each resource (Profile, Post, Note, Comment) has separate
```
.fields.ts
```
and
```
.operations.ts
```
files
Credentials:
```
credentials/SubstackApi.credentials.ts
```
- API authentication configuration
Types:
```
nodes/Substack/types.ts
```
- TypeScript interfaces for API responses

Resource-Based Architecture

The node supports four main resources, each with dedicated modules:

Profile (
```
Profile.fields.ts
```
,
```
Profile.operations.ts
```
)
- Get own profile, followees, publication data
Post (
```
Post.fields.ts
```
,
```
Post.operations.ts
```
)
- Retrieve posts with pagination support
Note (
```
Note.fields.ts
```
,
```
Note.operations.ts
```
)
- Create and retrieve notes, supports Markdown parsing
- Uses
```
MarkdownParser.ts
```
  for content transformation
Comment (
```
Comment.fields.ts
```
,
```
Comment.operations.ts
```
)
- Get comments for specific posts

Key Design Patterns

Operation Handler Pattern: Each resource exports operation handlers that the main node routes to
Client Caching: SubstackUtils maintains a Map-based cache of SubstackClient instances keyed by hostname+apiKey
Standardized Responses: All operations return
```
IStandardResponse
```
with consistent
```
success
```
,
```
data
```
,
```
error
```
structure
Error Handling: Uses n8n's
```
NodeOperationError
```
with proper item indexing and
```
continueOnFail
```
support

Dependencies

substack-api: External library handling actual Substack API communication (currently v1.3.0)
marked: Markdown parsing library used in Note operations
n8n-workflow: Core n8n types and utilities

Testing Architecture

The project uses Jest with a comprehensive mocking strategy:

Unit Tests Only: Located in
```
tests/unit/
```
, no integration tests
Mock Strategy: Direct mocking of
```
substack-api
```
module using
```
jest.mock()
```
Mock Components:
- ```
mockSubstackClient.ts
```
  : Mocks the SubstackClient with method chains
- ```
mockExecuteFunctions.ts
```
  : Simulates n8n's IExecuteFunctions interface
- ```
mockData.ts
```
  : Static fixtures matching Substack API format
Test Coverage: All operations, error handling, parameter validation, and edge cases

Build System

TypeScript: Strict configuration with declaration files
Gulp: Used for copying icon assets to dist directory
ESLint: Two configurations - standard and stricter pre-publish rules
Output: Compiled to
```
dist/
```
directory with proper n8n package structure

Development Workflow

Use
```
npm run dev
```
for TypeScript watch mode during development
Run
```
npm run test:watch
```
for continuous testing
Use
```
npm run lint
```
to check code style
Always run
```
npm run build
```
before publishing to ensure clean compilation
The
```
prepublishOnly
```
script runs additional strict linting checks

Common Development Commands

npm run build            # Full build: clean dist, compile TypeScript, copy icons
npm run dev             # Watch mode for TypeScript compilation
npm run format          # Format code with Prettier
npm run lint            # Lint code with ESLint  
npm run lintfix         # Auto-fix ESLint issues
npm run prepublishOnly  # Pre-publish checks: build + strict lint

npm test                # Run unit tests
npm run test:watch      # Run tests in watch mode
npm run test:unit       # Run unit tests (explicit)
npm run test:unit:watch # Watch unit tests during development

npm test -- <test-file-name>           # Run specific test file
npm test -- --testNamePattern="<name>" # Run tests matching pattern

Architecture Overview

This is an n8n community node package that provides Substack API integration. The project follows n8n's node development patterns with a modular resource-based architecture.

Main Node:

nodes/Substack/Substack.node.ts

- Central node implementation that routes operations to resource handlers

Utility Layer:

SubstackUtils.ts

- Client initialization, caching, response validation, and error handling

Resource Modules: Each resource (Profile, Post, Note, Comment) has separate

.fields.ts

and

.operations.ts

files

Credentials:

credentials/SubstackApi.credentials.ts

- API authentication configuration

Types:

nodes/Substack/types.ts

- TypeScript interfaces for API responses

The node supports four main resources, each with dedicated modules:

Profile (

Profile.fields.ts

Profile.operations.ts

)

Get own profile, followees, publication data

Post (

Post.fields.ts

Post.operations.ts

)

Retrieve posts with pagination support

Note (

Note.fields.ts

Note.operations.ts

)

Create and retrieve notes, supports Markdown parsing
Uses
```
MarkdownParser.ts
```
for content transformation

Comment (

Comment.fields.ts

Comment.operations.ts

)

Get comments for specific posts

Operation Handler Pattern: Each resource exports operation handlers that the main node routes to

Client Caching: SubstackUtils maintains a Map-based cache of SubstackClient instances keyed by hostname+apiKey

Standardized Responses: All operations return

IStandardResponse

with consistent

success

data

error

structure

Error Handling: Uses n8n's

NodeOperationError

with proper item indexing and

continueOnFail

support

substack-api: External library handling actual Substack API communication (currently v1.3.0)

marked: Markdown parsing library used in Note operations

n8n-workflow: Core n8n types and utilities

The project uses Jest with a comprehensive mocking strategy:

Unit Tests Only: Located in

tests/unit/

, no integration tests

Mock Strategy: Direct mocking of

substack-api

module using

jest.mock()

Mock Components:

```
mockSubstackClient.ts
```
: Mocks the SubstackClient with method chains
```
mockExecuteFunctions.ts
```
: Simulates n8n's IExecuteFunctions interface
```
mockData.ts
```
: Static fixtures matching Substack API format

Test Coverage: All operations, error handling, parameter validation, and edge cases

TypeScript: Strict configuration with declaration files

Gulp: Used for copying icon assets to dist directory

ESLint: Two configurations - standard and stricter pre-publish rules

Output: Compiled to

dist/

directory with proper n8n package structure

Use

npm run dev

for TypeScript watch mode during development

Run

npm run test:watch

for continuous testing

Use

npm run lint

to check code style

Always run

npm run build

before publishing to ensure clean compilation

The

prepublishOnly

script runs additional strict linting checks

CLAUDE.md

CLAUDE.md

Common Development Commands

Build and Development

Testing

Running Single Tests

Architecture Overview

Core Structure

Resource-Based Architecture

Key Design Patterns

Dependencies

Testing Architecture

Build System

Development Workflow

Related Skills

Markdown Converter

Nano Banana Pro

1password

CLAUDE.md

Common Development Commands

Build and Development

Testing

Running Single Tests

Architecture Overview

Core Structure

Resource-Based Architecture

Key Design Patterns

Dependencies

Testing Architecture

Build System

Development Workflow