@cimplify/sdk 0.2.0 → 0.2.2

package/README.md

@@ -0,0 +1,175 @@
+# @cimplify/sdk
+
+The official TypeScript SDK for building storefronts with the Cimplify Commerce Engine.
+
+## Installation
+
+```bash
+npm install @cimplify/sdk
+# or
+yarn add @cimplify/sdk
+# or
+bun add @cimplify/sdk
+```
+
+## Quick Start
+
+```typescript
+import { createCimplifyClient } from '@cimplify/sdk';
+
+const cimplify = createCimplifyClient();
+
+// Fetch products
+const products = await cimplify.catalogue.getProducts();
+
+// Add to cart
+await cimplify.cart.addItem({ item_id: 'product-id', quantity: 1 });
+
+// Get cart
+const cart = await cimplify.cart.get();
+```
+
+## Services
+
+### Catalogue
+
+```typescript
+// Products
+const products = await cimplify.catalogue.getProducts();
+const featured = await cimplify.catalogue.getProducts({ featured: true, limit: 10 });
+const product = await cimplify.catalogue.getProduct('product-id');
+const product = await cimplify.catalogue.getProductBySlug('my-product');
+
+// Variants
+const variants = await cimplify.catalogue.getVariants('product-id');
+const variant = await cimplify.catalogue.getVariantByAxisSelections('product-id', {
+  Size: 'Large',
+  Color: 'Red',
+});
+
+// Categories & Collections
+const categories = await cimplify.catalogue.getCategories();
+const collections = await cimplify.catalogue.getCollections();
+
+// Bundles & Composites
+const bundles = await cimplify.catalogue.getBundles();
+const composites = await cimplify.catalogue.getComposites();
+
+// Search
+const results = await cimplify.catalogue.search('coffee');
+```
+
+### Cart
+
+```typescript
+const cart = await cimplify.cart.get();
+const count = await cimplify.cart.getCount();
+
+await cimplify.cart.addItem({
+  item_id: 'product-id',
+  quantity: 2,
+  configuration: {
+    variant: { variant_id: 'variant-id' },
+    add_ons: [{ add_on_id: 'addon-id', quantity: 1 }],
+  },
+});
+
+await cimplify.cart.updateQuantity('cart-item-id', 3);
+await cimplify.cart.removeItem('cart-item-id');
+await cimplify.cart.clear();
+
+await cimplify.cart.applyCoupon('SUMMER20');
+await cimplify.cart.removeCoupon();
+```
+
+### Orders
+
+```typescript
+const orders = await cimplify.orders.getOrders();
+const order = await cimplify.orders.getOrder('order-id');
+```
+
+### Authentication
+
+```typescript
+const status = await cimplify.auth.getStatus();
+const user = await cimplify.auth.getCurrentUser();
+
+await cimplify.auth.requestOtp('+1234567890', 'phone');
+const result = await cimplify.auth.verifyOtp('123456', '+1234567890');
+await cimplify.auth.logout();
+```
+
+### Business & Locations
+
+```typescript
+const business = await cimplify.business.getBusiness();
+const locations = await cimplify.business.getLocations();
+```
+
+### Scheduling
+
+```typescript
+const slots = await cimplify.scheduling.getAvailableSlots({
+  location_id: 'location-id',
+  date: '2025-01-15',
+  service_type: 'delivery',
+});
+```
+
+### Inventory
+
+```typescript
+const stock = await cimplify.inventory.checkStock('product-id', 'location-id');
+```
+
+## Price Utilities
+
+```typescript
+import { formatPrice, formatPriceCompact, isOnSale, getDiscountPercentage } from '@cimplify/sdk';
+
+formatPrice(29.99, 'USD');          // "$29.99"
+formatPrice(29.99, 'GHS');          // "GH₵29.99"
+formatPriceCompact(2500000, 'USD'); // "$2.5M"
+
+if (isOnSale(product)) {
+  console.log(`${getDiscountPercentage(product)}% off!`);
+}
+```
+
+## Error Handling
+
+```typescript
+import { CimplifyError } from '@cimplify/sdk';
+
+try {
+  await cimplify.cart.addItem({ item_id: 'invalid', quantity: 1 });
+} catch (error) {
+  if (error instanceof CimplifyError) {
+    console.log(error.code);    // "PRODUCT_NOT_FOUND"
+    console.log(error.message); // "Product not found"
+  }
+}
+```
+
+## TypeScript
+
+```typescript
+import type {
+  Product,
+  ProductWithDetails,
+  ProductVariant,
+  Category,
+  Collection,
+  Bundle,
+  Composite,
+  Cart,
+  CartItem,
+  Order,
+  Customer,
+} from '@cimplify/sdk';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -2329,7 +2329,11 @@ declare class SchedulingService {
     private client;
     constructor(client: CimplifyClient);
     getServices(): Promise<Service[]>;
-    getService(serviceId: string): Promise<Service>;
+    /**
+     * Get a specific service by ID
+     * Note: Filters from all services client-side (no single-service endpoint)
+     */
+    getService(serviceId: string): Promise<Service | null>;
     getAvailableSlots(input: GetAvailableSlotsInput): Promise<AvailableSlot[]>;
     checkSlotAvailability(input: CheckSlotAvailabilityInput): Promise<{
         available: boolean;

package/dist/index.d.ts

@@ -2329,7 +2329,11 @@ declare class SchedulingService {
     private client;
     constructor(client: CimplifyClient);
     getServices(): Promise<Service[]>;
-    getService(serviceId: string): Promise<Service>;
+    /**
+     * Get a specific service by ID
+     * Note: Filters from all services client-side (no single-service endpoint)
+     */
+    getService(serviceId: string): Promise<Service | null>;
     getAvailableSlots(input: GetAvailableSlotsInput): Promise<AvailableSlot[]>;
     checkSlotAvailability(input: CheckSlotAvailabilityInput): Promise<{
         available: boolean;

package/dist/index.js

@@ -871,27 +871,32 @@ var SchedulingService = class {
   async getServices() {
     return this.client.query("scheduling.services");
   }
+  /**
+   * Get a specific service by ID
+   * Note: Filters from all services client-side (no single-service endpoint)
+   */
   async getService(serviceId) {
-    return this.client.query(`scheduling.services.${serviceId}`);
+    const services = await this.getServices();
+    return services.find((s) => s.id === serviceId) || null;
   }
   // --------------------------------------------------------------------------
   // AVAILABILITY
   // --------------------------------------------------------------------------
   async getAvailableSlots(input) {
     return this.client.query(
-      "scheduling.available_slots",
+      "scheduling.slots",
       input
     );
   }
   async checkSlotAvailability(input) {
     return this.client.query(
-      "scheduling.check_slot",
+      "scheduling.check_availability",
       input
     );
   }
   async getServiceAvailability(params) {
     return this.client.query(
-      "scheduling.service_availability",
+      "scheduling.availability",
       params
     );
   }
@@ -899,19 +904,19 @@ var SchedulingService = class {
   // BOOKINGS
   // --------------------------------------------------------------------------
   async getBooking(bookingId) {
-    return this.client.query(`scheduling.bookings.${bookingId}`);
+    return this.client.query(`scheduling.${bookingId}`);
   }
   async getCustomerBookings() {
-    return this.client.query("scheduling.customer_bookings");
+    return this.client.query("scheduling");
   }
   async getUpcomingBookings() {
     return this.client.query(
-      "scheduling.customer_bookings[?(@.status!='completed' && @.status!='cancelled')]#sort(start_time,asc)"
+      "scheduling[?(@.status!='completed' && @.status!='cancelled')]#sort(start_time,asc)"
     );
   }
   async getPastBookings(limit = 10) {
     return this.client.query(
-      `scheduling.customer_bookings[?(@.status=='completed')]#sort(start_time,desc)#limit(${limit})`
+      `scheduling[?(@.status=='completed')]#sort(start_time,desc)#limit(${limit})`
     );
   }
   // --------------------------------------------------------------------------

package/dist/index.mjs

@@ -869,27 +869,32 @@ var SchedulingService = class {
   async getServices() {
     return this.client.query("scheduling.services");
   }
+  /**
+   * Get a specific service by ID
+   * Note: Filters from all services client-side (no single-service endpoint)
+   */
   async getService(serviceId) {
-    return this.client.query(`scheduling.services.${serviceId}`);
+    const services = await this.getServices();
+    return services.find((s) => s.id === serviceId) || null;
   }
   // --------------------------------------------------------------------------
   // AVAILABILITY
   // --------------------------------------------------------------------------
   async getAvailableSlots(input) {
     return this.client.query(
-      "scheduling.available_slots",
+      "scheduling.slots",
       input
     );
   }
   async checkSlotAvailability(input) {
     return this.client.query(
-      "scheduling.check_slot",
+      "scheduling.check_availability",
       input
     );
   }
   async getServiceAvailability(params) {
     return this.client.query(
-      "scheduling.service_availability",
+      "scheduling.availability",
       params
     );
   }
@@ -897,19 +902,19 @@ var SchedulingService = class {
   // BOOKINGS
   // --------------------------------------------------------------------------
   async getBooking(bookingId) {
-    return this.client.query(`scheduling.bookings.${bookingId}`);
+    return this.client.query(`scheduling.${bookingId}`);
   }
   async getCustomerBookings() {
-    return this.client.query("scheduling.customer_bookings");
+    return this.client.query("scheduling");
   }
   async getUpcomingBookings() {
     return this.client.query(
-      "scheduling.customer_bookings[?(@.status!='completed' && @.status!='cancelled')]#sort(start_time,asc)"
+      "scheduling[?(@.status!='completed' && @.status!='cancelled')]#sort(start_time,asc)"
     );
   }
   async getPastBookings(limit = 10) {
     return this.client.query(
-      `scheduling.customer_bookings[?(@.status=='completed')]#sort(start_time,desc)#limit(${limit})`
+      `scheduling[?(@.status=='completed')]#sort(start_time,desc)#limit(${limit})`
     );
   }
   // --------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cimplify/sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Cimplify Commerce SDK for storefronts",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -12,7 +12,9 @@
       "require": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
@@ -24,6 +26,11 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2"
   },
-  "keywords": ["cimplify", "commerce", "sdk", "storefront"],
+  "keywords": [
+    "cimplify",
+    "commerce",
+    "sdk",
+    "storefront"
+  ],
   "license": "MIT"
 }