commerce-kit

commerce-kit

TypeScript SDK for building e-commerce apps. Works with Stripe and YNS APIs through a clean, unified interface. Built for Next.js, but plays nice with whatever you're using.

Built by Your Next Store.

Features

• Multi-provider: Switch between Stripe and YNS without changing code
• Class-based: Industry standard pattern like Stripe, OpenAI, AWS SDK
• Zero config: Works out of the box with environment variables
• Type-safe: Full TypeScript with provider-specific types
• GraphQL support: Field selection for YNS, REST for Stripe
• Multi-instance: Perfect for testing and multi-tenant apps

Install

npm install commerce-kit

Quick start

Zero config - works automatically with environment variables:

// Set environment variables:
// STRIPE_SECRET_KEY=sk_test_...
// or YNS_ENDPOINT=https://api.yournextstore.com and YNS_TOKEN=token_...

import commerce from "commerce-kit";
import { formatMoney } from "commerce-kit/currencies";

export async function ProductList() {
  const products = await commerce.product.browse({ first: 6 });

  return (
    <div>
      {products.data.map((product) => (
        <div key={product.id}>
          <h2>{product.name}</h2>
          <p>{formatMoney({ amount: product.price, currency: product.currency })}</p>
        </div>
      ))}
    </div>
  );
}

Explicit configuration:

import { Commerce } from "commerce-kit";

// Create your own instance with explicit config
const commerce = new Commerce({
  provider: "stripe",
  stripe: { secretKey: "sk_test_..." }
});

const products = await commerce.product.browse({ first: 6 });

Usage Patterns

1. Default Instance (Recommended)

import commerce from "commerce-kit";

// Auto-detects from STRIPE_SECRET_KEY or YNS_ENDPOINT/YNS_TOKEN
const products = await commerce.product.browse({ first: 10 });
const cart = await commerce.cart.add({ variantId: "var_123", quantity: 1 });

2. Commerce Class

import { Commerce } from "commerce-kit";

// Zero-config constructor
const commerce = new Commerce();

// Or explicit configuration
const commerce = new Commerce({
  provider: "stripe",
  stripe: { secretKey: "sk_test_..." }
});

const products = await commerce.product.browse({ first: 10 });

3. Provider-Specific Classes

import { StripeCommerce, YNSCommerce } from "commerce-kit";

// Stripe-specific client
const stripe = new StripeCommerce({ 
  secretKey: "sk_test_..." 
});

// YNS-specific client with GraphQL support
const yns = new YNSCommerce({
  endpoint: "https://api.yournextstore.com",
  token: "token_..."
});

const stripeProducts = await stripe.product.browse({ first: 10 });
const ynsProducts = await yns.product.browse({ 
  first: 10,
  fields: ["id", "name", "price"] // GraphQL field selection
});

API Reference

Products

import { Commerce } from "commerce-kit";
const commerce = new Commerce();

// Browse with filters
const products = await commerce.product.browse({
  first: 10,
  category: "electronics",
  fields: ["id", "name", "price"] // GraphQL field selection (YNS only)
});

// Get single product  
const product = await commerce.product.get({ slug: "awesome-laptop" });

// Search (YNS only)
const results = await commerce.product.search({ query: "macbook" });

Cart

import { Commerce } from "commerce-kit";
const commerce = new Commerce();

// Add to cart
const result = await commerce.cart.add({ 
  variantId: "variant_123",
  quantity: 2 
});

// Update quantity
await commerce.cart.update({ 
  cartId: result.cartId,
  variantId: "variant_123", 
  quantity: 3 
});

// Get cart
const cartData = await commerce.cart.get({ cartId: result.cartId });

Orders (YNS only)

import { YNSCommerce } from "commerce-kit";

const yns = new YNSCommerce({
  endpoint: process.env.YNS_ENDPOINT,
  token: process.env.YNS_TOKEN
});

// List orders
const orders = await yns.order.list({ first: 10 });

// Get single order
const order = await yns.order.get({ id: "order_123" });

Environment Variables

Set these environment variables for automatic configuration:

# For Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_TAG_PREFIX=my-store  # optional

# For YNS
YNS_ENDPOINT=https://api.yournextstore.com
YNS_TOKEN=token_...

# Optional: explicitly choose provider
COMMERCE_PROVIDER=stripe  # or "yns"

Multi-Tenant & Testing

Perfect for multi-tenant applications and testing:

// Multi-tenant
class TenantService {
  getCommerce(tenantId: string) {
    const config = this.getTenantConfig(tenantId);
    return new Commerce(config);
  }
}

// Testing
describe("Product Service", () => {
  it("should fetch products", async () => {
    const commerce = new Commerce({
      provider: "stripe",
      stripe: { secretKey: "sk_test_mock" }
    });
    
    const products = await commerce.product.browse();
    expect(products).toBeDefined();
  });
});

Why Class-Based?

Following industry standards from Stripe, OpenAI, and AWS SDK:

• ✅ Explicit initialization - Clear where configuration happens
• ✅ Multiple instances - Multi-tenant and testing support
• ✅ Type safety - Better TypeScript integration
• ✅ No global state - Each instance is isolated
• ✅ Familiar pattern - Same as new Stripe(), new OpenAI()

License

AGPL-3.0 – see LICENSE.md