commerce-kit 0.0.41 → 0.2.0

package/README.md

@@ -1,75 +1,234 @@
 # commerce-kit
 
-`commerce-kit` is a simple TypeScript library designed specifically for e-commerce applications built with Next.js. It provides a range of utilities to interact with products, categories, and orders, seamlessly integrating with Stripe for payment processing.
+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](https://yournextstore.com).
 
 ## Features
 
-- **Product Browsing**: Easily fetch and display products.
-- **Category Management**: Manage and retrieve product categories.
-- **Order Handling**: Create and manage customer orders.
-- **Cart Operations**: Add products to cart and retrieve cart details.
-- **Stripe Integration**: Built-in support for payment processing using Stripe.
+- **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
 
-## Installation
-
-Install the package via npm:
+## Install
 
 ```bash
 npm install commerce-kit
 ```
 
-## Usage
+## Quick start
 
-`commerce-kit` is intended for use with Next.js applications. Here's a simple example of how to use it to fetch and display products:
+**Zero config** - works automatically with environment variables:
 
 ```tsx
-import * as Commerce from "commerce-kit";
+// 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";
-import Image from "next/image";
-import Link from "next/link";
 
 export async function ProductList() {
-  const products = await Commerce.productBrowse({ first: 6 });
+  const products = await commerce.product.browse({ first: 6 });
 
   return (
-    <ul>
-      {products.map((product) => (
-        <li key={product.id}>
-          <Link href={`/product/${product.metadata.slug}`}>
-            <article>
-              {product.images[0] && (
-                <Image src={product.images[0]} width={300} height={300} alt={product.name} />
-              )}
-              <h2>{product.name}</h2>
-              {product.default_price.unit_amount && (
-                <p>
-                  {formatMoney({
-                    amount: product.default_price.unit_amount,
-                    currency: product.default_price.currency,
-                    locale: "en-US",
-                  })}
-                </p>
-              )}
-            </article>
-          </Link>
-        </li>
+    <div>
+      {products.data.map((product) => (
+        <div key={product.id}>
+          <h2>{product.name}</h2>
+          <p>{formatMoney({ amount: product.price, currency: product.currency })}</p>
+        </div>
       ))}
-    </ul>
+    </div>
   );
 }
 ```
 
-## Debugging
+**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({
+  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
+
+```tsx
+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)
+
+```tsx
+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:
+
+```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"
+```
+
+## Multi-Tenant & Testing
+
+Perfect for multi-tenant applications and testing:
+
+```tsx
+// 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?
 
-This library uses a custom logger to output debug information. To control the debug output, use the `LOG_LEVEL` environment variable. The following levels are supported:
+Following industry standards from Stripe, OpenAI, and AWS SDK:
 
-- **ERROR** – Critical issue for a specific request that needs immediate attention.
-- **WARN** – Something that should be reviewed eventually.
-- **LOG** – Details on regular operations.
-- **DEBUG** – Debug information, including `time` and `timeEnd` function outputs.
+- ✅ **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
 
-This project is licensed under the AGPL Version 3 license – see the LICENSE.md file for details.
+AGPL-3.0 – see LICENSE.md