Package Exports

@profullstack/stripe-config

Readme

@profullstack/stripe-config

A powerful CLI tool and ESM module for managing Stripe products and prices across multiple projects.

Features

🔧 CLI Tool - Interactive command-line interface for managing Stripe resources
📦 ESM Module - Programmatic API for Node.js applications
🔐 Secure Storage - API keys stored in ~/.config/stripeconf with proper permissions
🎯 Multi-Project - Manage multiple Stripe projects from a single configuration
💰 Full CRUD - Complete product and price lifecycle management
🔄 Recurring Prices - Support for subscriptions with flexible billing intervals
📊 Advanced Features - Metadata, images, tax codes, tiered pricing, and more
🎨 TypeScript - Full type definitions included

Installation

pnpm add @profullstack/stripe-config

Or install globally for CLI usage:

pnpm add -g @profullstack/stripe-config

CLI Usage

Setup

Configure a new Stripe project:

stripeconf setup

This will prompt you for:

Project name
Environment (test/live)
API keys (publishable and secret)
Webhook secret (optional)
Default currency

Manage Products

stripeconf products

Operations available:

List all products
View product details
Create new product
Update existing product
Delete product

Manage Prices

stripeconf prices

Operations available:

List all prices
View price details
Create new price (one-time or recurring)
Update price
Archive price

Programmatic Usage

Basic Example

import { ConfigManager, StripeClient } from '@profullstack/stripe-config';

// Load configuration
const config = new ConfigManager();
const project = await config.getDefaultProject();

// Initialize Stripe client
const stripe = new StripeClient(project);

// List products
const products = await stripe.listProducts({ limit: 10 });
console.log(`Found ${products.length} products`);

Using High-Level Managers

import { ConfigManager, ProductManager, PriceManager } from '@profullstack/stripe-config';

// Load configuration
const config = new ConfigManager();
const project = await config.getDefaultProject();

// Initialize managers
const products = new ProductManager(project);
const prices = new PriceManager(project);

// Create a product
const product = await products.create({
  name: 'Premium Plan',
  description: 'Full access to all features',
  active: true,
  metadata: { tier: 'premium' }
});

// Create a recurring price
const price = await prices.create({
  product: product.id,
  currency: 'usd',
  unit_amount: 2999, // $29.99
  recurring: {
    interval: 'month',
    interval_count: 1
  }
});

Managing Configuration

import { ConfigManager } from '@profullstack/stripe-config';

const config = new ConfigManager();

// Add a new project
await config.addProject({
  name: 'my-project',
  environment: 'test',
  publishableKey: 'pk_test_...',
  secretKey: 'sk_test_...',
  defaultCurrency: 'usd'
});

// List all projects
const projects = await config.listProjects();

// Get a specific project
const project = await config.getProject('my-project');

// Set default project
await config.setDefaultProject('my-project');

// Update project
await config.updateProject('my-project', {
  defaultCurrency: 'eur'
});

// Delete project
await config.deleteProject('my-project');

API Reference

ConfigManager

Manages project configurations stored in ~/.config/stripeconf/config.json.

class ConfigManager {
  constructor(configPath?: string);
  
  async addProject(project: Omit<ProjectConfig, 'id' | 'createdAt' | 'updatedAt'>): Promise<ProjectConfig>;
  async getProject(name: string): Promise<ProjectConfig>;
  async listProjects(): Promise<ProjectConfig[]>;
  async updateProject(name: string, updates: Partial<ProjectConfig>): Promise<ProjectConfig>;
  async deleteProject(name: string): Promise<void>;
  async setDefaultProject(name: string): Promise<void>;
  async getDefaultProject(): Promise<ProjectConfig>;
}

StripeClient

Low-level wrapper around the Stripe SDK.

class StripeClient {
  constructor(project: ProjectConfig);
  
  // Products
  async createProduct(input: CreateProductInput): Promise<Stripe.Product>;
  async getProduct(productId: string): Promise<Stripe.Product>;
  async updateProduct(productId: string, updates: UpdateProductInput): Promise<Stripe.Product>;
  async deleteProduct(productId: string): Promise<void>;
  async listProducts(options?: ListOptions): Promise<Stripe.Product[]>;
  
  // Prices
  async createPrice(input: CreatePriceInput): Promise<Stripe.Price>;
  async getPrice(priceId: string): Promise<Stripe.Price>;
  async updatePrice(priceId: string, updates: UpdatePriceInput): Promise<Stripe.Price>;
  async listPrices(options?: PriceListOptions): Promise<Stripe.Price[]>;
  async archivePrice(priceId: string): Promise<Stripe.Price>;
}

ProductManager

High-level API for product operations.

class ProductManager {
  constructor(project: ProjectConfig);
  
  async create(input: CreateProductInput): Promise<Stripe.Product>;
  async get(productId: string): Promise<Stripe.Product>;
  async update(productId: string, updates: UpdateProductInput): Promise<Stripe.Product>;
  async delete(productId: string): Promise<void>;
  async list(options?: ListOptions): Promise<Stripe.Product[]>;
}

PriceManager

High-level API for price operations.

class PriceManager {
  constructor(project: ProjectConfig);
  
  async create(input: CreatePriceInput): Promise<Stripe.Price>;
  async get(priceId: string): Promise<Stripe.Price>;
  async update(priceId: string, updates: UpdatePriceInput): Promise<Stripe.Price>;
  async archive(priceId: string): Promise<Stripe.Price>;
  async list(options?: PriceListOptions): Promise<Stripe.Price[]>;
  async listByProduct(productId: string): Promise<Stripe.Price[]>;
}

Type Definitions

All TypeScript types are exported from the main module:

import type {
  ProjectConfig,
  Config,
  CreateProductInput,
  UpdateProductInput,
  CreatePriceInput,
  UpdatePriceInput,
  RecurringConfig,
  TierConfig,
  ListOptions,
  PriceListOptions,
} from '@profullstack/stripe-config';

Configuration File

Configuration is stored in ~/.config/stripeconf/config.json:

{
  "version": "1.0.0",
  "projects": [
    {
      "id": "uuid",
      "name": "my-project",
      "environment": "test",
      "publishableKey": "pk_test_...",
      "secretKey": "sk_test_...",
      "webhookSecret": "whsec_...",
      "defaultCurrency": "usd",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "defaultProject": "my-project"
}

Security

Configuration files are stored with 0600 permissions (owner read/write only)
Configuration directory has 0700 permissions (owner full access only)
API keys are never logged or displayed in error messages
All user inputs are validated before API calls

Examples

See the examples/ directory for more usage examples:

basic-usage.js - Basic configuration and product listing
create-product.js - Creating products with prices

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Build
pnpm build

# Lint
pnpm lint

# Format code
pnpm format

Testing

The project uses Vitest for testing with comprehensive unit test coverage:

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Generate coverage report
pnpm test:coverage

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.