commerce-kit 0.1.0 → 0.2.0

package/README.md

@@ -7,10 +7,11 @@ Built by [Your Next Store](https://yournextstore.com).
 ## Features
 
 - **Multi-provider**: Switch between Stripe and YNS without changing code
-- **GraphQL support**: Field selection for YNS, REST for Stripe
+- **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
-- **Tree-shakeable**: Only bundle what you use
-- **Zero config**: Works out of the box, customize when needed
+- **GraphQL support**: Field selection for YNS, REST for Stripe
+- **Multi-instance**: Perfect for testing and multi-tenant apps
 
 ## Install
 
@@ -20,19 +21,18 @@ npm install commerce-kit
 
 ## Quick start
 
+**Zero config** - works automatically with environment variables:
+
 ```tsx
-import * as Commerce from "commerce-kit";
-import { formatMoney } from "commerce-kit/currencies";
+// Set environment variables:
+// STRIPE_SECRET_KEY=sk_test_...
+// or YNS_ENDPOINT=https://api.yournextstore.com and YNS_TOKEN=token_...
 
-// Configure once
-Commerce.configure({
-  provider: "stripe", // or "yns"
-  stripe: { secretKey: process.env.STRIPE_SECRET_KEY }
-});
+import commerce from "commerce-kit";
+import { formatMoney } from "commerce-kit/currencies";
 
-// Use everywhere
 export async function ProductList() {
-  const products = await Commerce.product.browse({ first: 6 });
+  const products = await commerce.product.browse({ first: 6 });
 
   return (
     <div>
@@ -47,97 +47,188 @@ export async function ProductList() {
 }
 ```
 
-## API
+**Explicit configuration**:
+
+```tsx
+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)
+
+```tsx
+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
+
+```tsx
+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
+
+```tsx
+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
+
 ```tsx
+import { Commerce } from "commerce-kit";
+const commerce = new Commerce();
+
 // Browse with filters
-const products = await Commerce.product.browse({
+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" });
+const product = await commerce.product.get({ slug: "awesome-laptop" });
 
-// Search
-const results = await Commerce.product.search({ query: "macbook" });
+// Search (YNS only)
+const results = await commerce.product.search({ query: "macbook" });
 ```
 
 ### Cart
+
 ```tsx
+import { Commerce } from "commerce-kit";
+const commerce = new Commerce();
+
 // Add to cart
-const cart = await Commerce.cart.add({ 
+const result = await commerce.cart.add({ 
   variantId: "variant_123",
   quantity: 2 
 });
 
 // Update quantity
-await Commerce.cart.update({ 
-  cartId: cart.cartId,
+await commerce.cart.update({ 
+  cartId: result.cartId,
   variantId: "variant_123", 
   quantity: 3 
 });
 
 // Get cart
-const cartData = await Commerce.cart.get({ cartId: cart.cartId });
+const cartData = await commerce.cart.get({ cartId: result.cartId });
 ```
 
-### Provider switching
+### Orders (YNS only)
+
 ```tsx
-// Override provider per call
-const stripeProducts = await Commerce.product.browse({ 
-  first: 10,
-  _provider: "stripe" 
+import { YNSCommerce } from "commerce-kit";
+
+const yns = new YNSCommerce({
+  endpoint: process.env.YNS_ENDPOINT,
+  token: process.env.YNS_TOKEN
 });
 
-// Or use scoped instances
-const yns = Commerce.withProvider("yns");
-const stripe = Commerce.withProvider("stripe");
+// List orders
+const orders = await yns.order.list({ first: 10 });
 
-const ynsProducts = await yns.product.browse({ first: 10 });
-const stripeProducts = await stripe.product.browse({ first: 10 });
+// Get single order
+const order = await yns.order.get({ id: "order_123" });
 ```
 
-## Providers
+## Environment Variables
 
-### YNS
-```tsx
-Commerce.configure({
-  provider: "yns",
-  yns: {
-    endpoint: "https://api.yournextstore.com",
-    token: process.env.YNS_API_TOKEN
-  }
-});
+Set these environment variables for automatic configuration:
+
+```bash
+# 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"
 ```
 
-### Stripe  
+## Multi-Tenant & Testing
+
+Perfect for multi-tenant applications and testing:
+
 ```tsx
-Commerce.configure({
-  provider: "stripe",
-  stripe: {
-    secretKey: process.env.STRIPE_SECRET_KEY,
-    tagPrefix: "my-store" // optional
+// 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();
+  });
 });
 ```
 
-## Migration
+## Why Class-Based?
 
-Old way (still works):
-```tsx
-const products = await Commerce.productBrowse({ first: 6 });
-```
-
-New way (recommended):
-```tsx  
-const products = await Commerce.product.browse({ first: 6 });
-```
+Following industry standards from Stripe, OpenAI, and AWS SDK:
 
-Same data, better DX, provider flexibility, GraphQL field selection.
+- ✅ **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
+AGPL-3.0 – see LICENSE.md