commerce-kit 0.6.1-experimental.8 → 0.7.0

package/README.md

@@ -0,0 +1,234 @@
+# 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](https://yournextstore.com).
+
+## 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
+
+```bash
+npm install commerce-kit
+```
+
+## Quick start
+
+**Zero config** - works automatically with environment variables:
+
+```tsx
+// 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**:
+
+```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?
+
+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

package/dist/currencies.d.ts

@@ -0,0 +1,11 @@
+type Money = {
+    amount: number;
+    currency: string;
+};
+declare const getStripeAmountFromDecimal: ({ amount: major, currency }: Money) => number;
+declare const getDecimalFromStripeAmount: ({ amount: minor, currency }: Money) => number;
+declare const formatMoney: ({ amount: minor, currency, locale }: Money & {
+    locale?: string;
+}) => string;
+
+export { formatMoney, getDecimalFromStripeAmount, getStripeAmountFromDecimal };

package/dist/currencies.js

@@ -0,0 +1 @@
+function o(e,n){if(!e)throw new Error(n)}var s=e=>{o(Number.isInteger(e),"Value must be an integer")};var u=e=>(o(e.length===3,"currency needs to be a 3-letter code"),a[e.toUpperCase()]??2),m=({amount:e,currency:n})=>{let t=10**u(n);return Number.parseInt((e*t).toFixed(0),10)},i=({amount:e,currency:n})=>{s(e);let r=u(n),t=10**r;return Number.parseFloat((e/t).toFixed(r))},p=({amount:e,currency:n,locale:r="en-US"})=>{let t=i({amount:e,currency:n});return new Intl.NumberFormat(r,{style:"currency",currency:n}).format(t)},a={BIF:0,CLP:0,DJF:0,GNF:0,JPY:0,KMF:0,KRW:0,MGA:0,PYG:0,RWF:0,UGX:0,VND:0,VUV:0,XAF:0,XOF:0,XPF:0,BHD:3,JOD:3,KWD:3,OMR:3,TND:3};export{p as formatMoney,i as getDecimalFromStripeAmount,m as getStripeAmountFromDecimal};

package/dist/index.d.ts

@@ -1,26 +1,6 @@
-import { APIProductsBrowseQueryParams, APIProductsBrowseResult, APIProductGetByIdParams, APIProductGetByIdResult, APIOrdersBrowseQueryParams, APIOrdersBrowseResult, APIOrderGetByIdParams, APIOrderGetByIdResult, APICartCreateBody, APICartCreateResult, APICartGetResult } from './api-types.js';
-export { APICartAddBody, APICartAddResult, APICartRemoveItemQueryParams, APICartRemoveItemResult, JSONContent } from './api-types.js';
-
-interface YnsProviderConfig {
-    version: "v1";
-    endpoint: string;
-    token: string;
-}
-declare class YnsProvider {
-    #private;
-    constructor(config: YnsProviderConfig);
-    productBrowse(params: APIProductsBrowseQueryParams): Promise<APIProductsBrowseResult>;
-    productGet(params: APIProductGetByIdParams): Promise<APIProductGetByIdResult | null>;
-    orderBrowse(params: APIOrdersBrowseQueryParams): Promise<APIOrdersBrowseResult>;
-    orderGet(params: APIOrderGetByIdParams): Promise<APIOrderGetByIdResult | null>;
-    cartUpsert(body: APICartCreateBody): Promise<APICartCreateResult>;
-    cartRemoveItem(params: {
-        cartId: string;
-        variantId: string;
-    }): Promise<null>;
-    cartGet(params: {
-        cartId: string;
-    }): Promise<APICartGetResult | null>;
-}
-
-export { APICartCreateBody, APICartCreateResult, APICartGetResult, APIOrderGetByIdParams, APIOrderGetByIdResult, APIOrdersBrowseQueryParams, APIOrdersBrowseResult, APIProductGetByIdParams, APIProductGetByIdResult, APIProductsBrowseQueryParams, APIProductsBrowseResult, YnsProvider };
+export { formatMoney } from './currencies.js';
+export { MappedCart, MappedProduct, MappedShippingRate } from './internal.js';
+export { B as BaseProvider, C as Cart, a as CartAddParams, b as CartClearParams, c as CartGetParams, d as CartItem, e as CartRemoveParams, f as CartUpdateParams, g as Customer, O as Order, h as OrderGetParams, i as OrderListParams, j as OrderListResult, P as Product, k as ProductBrowseParams, l as ProductBrowseResult, m as ProductGetParams, n as ProductInfo, o as ProductSearchParams, p as ProductSearchResult, S as StripeProviderConfig, Y as YnsProduct, q as YnsProviderConfig } from './provider-CeP9uHnB.js';
+export { Commerce } from './yns.js';
+import 'stripe';
+import 'zod';

package/dist/index.js

@@ -1,2 +1 @@
-import"./chunk-PNKB6P4V.js";var n={DEBUG:0,LOG:1,WARN:2,ERROR:3},p=process.env.NEXT_PUBLIC_LOG_LEVEL||"LOG",i=n[p],d="\x1B[0m",R="\x1B[34m",y="\x1B[32m",B="\x1B[33m",w="\x1B[31m",E="\u23F1\uFE0F",h="\u{1F41B}",A="\u2714\uFE0F",L="\u26A0\uFE0F",$="\u274C",f=`${E} `,G=`${R}${h}${d} `,O=`${y}${A}${d} `,v=`${B}${L}${d} `,C=`${w}${$}${d} `,l=a=>{let e=a?`[${a}] `:"";return{getLogger(t){return l([a,t].filter(Boolean).join(" > "))},time(t){i>n.DEBUG||console.time([f,e,t].filter(Boolean).join(" "))},timeEnd(t){i>n.DEBUG||console.timeEnd([f,e,t].filter(Boolean).join(" "))},debug(...t){i>n.DEBUG||console.log(...[G,e,...t].filter(Boolean))},log(...t){i>n.LOG||console.log(...[O,e,...t].filter(Boolean))},dir(t,r){i>n.LOG||console.dir(t,r)},warn(...t){i>n.WARN||console.warn(...[v,e,...t].filter(Boolean))},error(...t){i>n.ERROR||console.error(...[C,e,...t].filter(Boolean))}}},T=l();var I=class{#t;#r=l("YnsProvider");constructor(e){this.#t=e,this.#r.debug("YnsProvider initialized")}async#e(e,t="GET",r){let c=this.#r.getLogger("#restRequest"),s=`${this.#t.endpoint}/api/${this.#t.version}${e}`;c.debug(`Making ${t} request to YNS API: ${s}`);let o=await fetch(s,{method:t,headers:{"Content-Type":"application/json",Authorization:`Bearer ${this.#t.token}`},body:r?JSON.stringify(r):void 0});if(!o.ok){let m=o.headers.get("content-type"),u=`YNS REST request failed: ${o.status} ${o.statusText}`;if(m?.includes("application/json"))try{let g=await o.json();u=g.error||g.message||u}catch{}throw c.error(`YNS API request failed: ${o.status} ${o.statusText}`,u),new Error(u)}let P=o.headers.get("content-type");if(!P?.includes("application/json"))throw new Error(`YNS API returned ${P} instead of JSON for ${e}`);return o.json()}async productBrowse(e){let t=this.#r.getLogger("productBrowse");t.debug("Browsing products with params:",e);let r=new URLSearchParams;e.limit&&r.append("limit",e.limit.toString()),e.offset&&r.append("offset",e.offset.toString()),e.category&&r.append("category",e.category),e.query&&r.append("query",e.query),e.active!==void 0&&r.append("active",e.active.toString()),e.orderBy&&r.append("orderBy",e.orderBy),e.orderDirection&&r.append("orderDirection",e.orderDirection);let s=`/products${r.size?`?${r}`:""}`;t.debug("Constructed pathname:",s);let o=await this.#e(s);return t.debug("Received product browse result:",{meta:o.meta}),o}async productGet(e){let t=`/products/${e.idOrSlug}`,r=await this.#e(t);return r||null}async orderBrowse(e){let t=this.#r.getLogger("orderBrowse");t.debug("Browsing orders with params:",e);let r=new URLSearchParams;e.limit&&r.append("limit",e.limit.toString()),e.offset&&r.append("offset",e.offset.toString());let s=`/orders${r.size?`?${r}`:""}`;t.debug("Constructed pathname:",s);let o=await this.#e(s);return t.debug("Received orders browse result:",{meta:o.meta}),o}async orderGet(e){let t=`/orders/${e.id}`,r=await this.#e(t);return r||null}async cartUpsert(e){return await this.#e("/carts","POST",e)}async cartRemoveItem(e){let t=`/carts/${e.cartId}/line-items/${e.variantId}`,r=await this.#e(t,"DELETE");return null}async cartGet(e){let t=`/carts/${e.cartId}`;return await this.#e(t)}};export{I as YnsProvider};
-//# sourceMappingURL=index.js.map
+var v=Object.defineProperty;var f=(o,r)=>()=>(o&&(r=o(o=0)),r);var g=(o,r)=>{for(var t in r)v(o,t,{get:r[t],enumerable:!0})};var P={};g(P,{YnsProvider:()=>d,createYnsProvider:()=>I});function I(o){return new d(o)}var d,l=f(()=>{"use strict";d=class{config;constructor(r){this.config=r}async graphqlRequest(r,t){let e=await fetch(`${this.config.endpoint}/api/graphql`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${this.config.token}`},body:JSON.stringify({query:r,variables:t})});if(!e.ok)throw new Error(`YNS GraphQL request failed: ${e.status} ${e.statusText}`);let i=await e.json();if(i.errors)throw new Error(`YNS GraphQL errors: ${JSON.stringify(i.errors)}`);return i.data}async restRequest(r,t="GET",e){let i=await fetch(`${this.config.endpoint}/api/v1${r}`,{method:t,headers:{"Content-Type":"application/json",Authorization:`Bearer ${this.config.token}`},body:e?JSON.stringify(e):void 0});if(!i.ok){let s=i.headers.get("content-type"),n=`YNS REST request failed: ${i.status} ${i.statusText}`;if(s?.includes("application/json"))try{let p=await i.json();n=p.error||p.message||n}catch{}throw new Error(n)}let a=i.headers.get("content-type");if(!a?.includes("application/json"))throw new Error(`YNS API returned ${a} instead of JSON for ${r}`);return i.json()}mapYnsProduct(r){return{id:r.id,name:r.name,slug:r.slug,summary:r.summary,images:r.images||[],active:r.active,price:r.variants?.[0]?.price?Number.parseFloat(r.variants[0].price):0,currency:"USD",stock:r.variants?.[0]?.stock,category:r.category,variants:r.variants?.map(t=>({id:t.id,price:Number.parseFloat(t.price),stock:t.stock,attributes:t.attributes}))||[]}}mapCart(r){let t=this.mapCartItems(r.lineItems);return{id:r.id,customerId:r.customerId,storeId:r.storeId,customer:this.mapCustomer(r.customer),items:t,total:this.calculateTotal(t),currency:"USD",createdAt:r.createdAt,updatedAt:r.updatedAt}}mapCartItems(r){return r?.map(t=>this.mapCartItem(t))||[]}mapCartItem(r){let t=r.productVariant;return{id:r.id,productId:t?.product?.id||t?.id||"",variantId:t?.id,quantity:r.quantity,price:Number.parseFloat(t?.price||"0"),stock:t?.stock,product:this.mapProduct(t?.product)}}mapCustomer(r){if(r)return{id:r.id,email:r.email}}mapProduct(r){if(r)return{id:r.id,name:r.name,images:r.images||[]}}calculateTotal(r){return r.reduce((t,e)=>t+e.price*e.quantity,0)}async productBrowse(r){if(r.graphql){let t={offset:r.offset||0,limit:r.first||10,category:r.category,query:r.query,active:r.active,orderBy:r.orderBy,orderDirection:r.orderDirection},e=await this.graphqlRequest(r.graphql,t);return{data:e.products.data.map(i=>this.mapYnsProduct(i)),meta:e.products.meta}}else{let t=new URLSearchParams;r.first&&t.append("limit",r.first.toString()),r.offset&&t.append("offset",r.offset.toString()),r.category&&t.append("category",r.category),r.query&&t.append("q",r.query),r.active!==void 0&&t.append("active",r.active.toString()),r.orderBy&&t.append("orderBy",r.orderBy),r.orderDirection&&t.append("orderDirection",r.orderDirection);let e=`/products${t.toString()?`?${t.toString()}`:""}`,i=await this.restRequest(e);return{data:i.data.map(a=>this.mapYnsProduct(a)),meta:i.meta}}}async productGet(r){if(!r.slug&&!r.id)throw new Error("Either slug or id is required for productGet");if(r.graphql){let t={slug:r.slug,id:r.id},e=await this.graphqlRequest(r.graphql,t);return e.product?this.mapYnsProduct(e.product):null}else{let t=`/products/${r.id||r.slug}`,e=await this.restRequest(t);return e?this.mapYnsProduct(e):null}}async cartAdd(r){let t=r.quantity;if(r.cartId)try{let a=await this.cartGet({cartId:r.cartId});if(a){let s=a.items.find(n=>n.variantId===r.variantId);s&&(t=s.quantity+r.quantity)}}catch{}let e={variantId:r.variantId,cartId:r.cartId,quantity:t,subscriptionId:r.subscriptionId},i=await this.restRequest("/cart","POST",e);return this.mapCart(i)}async cartUpdate(r){let t={variantId:r.variantId,cartId:r.cartId,quantity:r.quantity},e=await this.restRequest("/cart","POST",t);return this.mapCart(e)}async cartRemove(r){let t=`/cart/${r.cartId}/items/${r.variantId}`,e=await this.restRequest(t,"DELETE");return this.mapCart(e)}async cartClear(r){let t=await this.restRequest(`/cart/${r.cartId}`,"DELETE");return this.mapCart(t)}async cartGet(r){let t=await this.restRequest(`/cart/${r.cartId}`);return t?this.mapCart(t):null}}});function c(o,r){if(!o)throw new Error(r)}var m=o=>{c(Number.isInteger(o),"Value must be an integer")};var y=o=>(c(o.length===3,"currency needs to be a 3-letter code"),w[o.toUpperCase()]??2);var h=({amount:o,currency:r})=>{m(o);let t=y(r),e=10**t;return Number.parseFloat((o/e).toFixed(t))},C=({amount:o,currency:r,locale:t="en-US"})=>{let e=h({amount:o,currency:r});return new Intl.NumberFormat(t,{style:"currency",currency:r}).format(e)},w={BIF:0,CLP:0,DJF:0,GNF:0,JPY:0,KMF:0,KRW:0,MGA:0,PYG:0,RWF:0,UGX:0,VND:0,VUV:0,XAF:0,XOF:0,XPF:0,BHD:3,JOD:3,KWD:3,OMR:3,TND:3};var u=class{config;provider;providerPromise;constructor(r){if(this.config=r||this.detectFromEnv(),!this.config.endpoint||!this.config.token)throw new Error("YNS configuration required. Provide endpoint and token in constructor or set YNS_ENDPOINT and YNS_TOKEN environment variables.")}detectFromEnv(){return{endpoint:process.env.YNS_ENDPOINT||"",token:process.env.YNS_TOKEN||""}}async getProvider(){return this.provider?this.provider:(this.providerPromise||(this.providerPromise=this.loadProvider()),this.provider=await this.providerPromise,this.provider)}async loadProvider(){try{let{createYnsProvider:r}=await Promise.resolve().then(()=>(l(),P));return r(this.config)}catch(r){throw new Error(`Failed to initialize YNS provider: ${r instanceof Error?r.message:"Unknown error"}`)}}get product(){return{browse:async(r={})=>(await this.getProvider()).productBrowse(r),get:async r=>(await this.getProvider()).productGet(r),search:async r=>{let t=await this.getProvider();if(!t.productSearch)throw new Error("Product search is not supported by YNS provider");return t.productSearch(r)}}}get cart(){return{add:async r=>(await this.getProvider()).cartAdd(r),update:async r=>(await this.getProvider()).cartUpdate(r),remove:async r=>(await this.getProvider()).cartRemove(r),clear:async r=>(await this.getProvider()).cartClear(r),get:async r=>(await this.getProvider()).cartGet(r)}}get order(){return{get:async r=>{let t=await this.getProvider();if(!t.orderGet)throw new Error("Order retrieval is not supported by YNS provider");return t.orderGet(r)},list:async(r={})=>{let t=await this.getProvider();if(!t.orderList)throw new Error("Order listing is not supported by YNS provider");return t.orderList(r)}}}};export{u as Commerce,C as formatMoney};