@orbiocloud/shop-sdk

JavaScript SDK for integrating with OrbioShop e-commerce API.

Installation

npm install @orbiocloud/shop-sdk
# or
yarn add @orbiocloud/shop-sdk
# or
pnpm add @orbiocloud/shop-sdk

Quick Start

import { OrbioShopClient } from '@orbiocloud/shop-sdk';

const shop = new OrbioShopClient({
  apiKey: 'your-api-key',
  subdomain: 'my-store',
});

// Get products
const { data: products } = await shop.getProducts({ limit: 10 });

// Add to cart
const cart = await shop.addToCart({
  product_id: 'prod_123',
  quantity: 1
});

// Checkout with Stripe
const { data } = await shop.createStripeCheckout({
  customer_email: '[email protected]',
  shipping_address: {
    first_name: 'John',
    last_name: 'Doe',
    address_line1: '123 Main St',
    city: 'Anytown',
    state: 'CA',
    postal_code: '12345',
    country: 'US',
  },
  success_url: 'https://mysite.com/success',
  cancel_url: 'https://mysite.com/cancel',
});

// Redirect to Stripe checkout
window.location.href = data.checkout_url;

API Reference

Configuration

const shop = new OrbioShopClient({
  apiKey: string;      // Required: Your OrbioShop API key
  subdomain: string;   // Required: Your store subdomain
  baseUrl?: string;    // Optional: Custom API base URL
});

Products

// List products with filters
const response = await shop.getProducts({
  page: 1,
  limit: 20,
  category: 'electronics',
  search: 'laptop',
  featured: true,
  sort: 'price',
  order: 'asc',
});

// Get single product
const product = await shop.getProduct('product-slug');

// Search products
const results = await shop.searchProducts('laptop', 10);

Product feed + deep-link (read-only embed)

For showing products on another site (a homepage, a blog) and sending shoppers to your storefront, use a publishable read-only key and the deep-link helper. The base URL defaults to https://<subdomain>.shop.orbiocloud.com; pass baseUrl to keep links on your brand domain.

const shop = new OrbioShopClient({
  apiKey: 'your-publishable-read-key',
  subdomain: 'my-store',
  // baseUrl: 'https://shop.acme.com', // optional brand domain
});

const { data: products } = await shop.getProducts({ limit: 12, featured: true });

// Storefront product-page URL for any product (slug is encoded):
const href = shop.productUrl(products[0].slug);
// -> https://my-store.shop.orbiocloud.com/shop/product/<slug>

// "View cart" / "Checkout" button -> the hosted storefront cart (checkout runs there):
const cart = shop.cartUrl();
// -> https://my-store.shop.orbiocloud.com/shop/cart

The ready-made <orbio-product-list> / <orbio-product-card> drop-in widgets are in @orbiocloud/shop-widgets.

Categories

const categories = await shop.getCategories();

Cart

// Get cart
const cart = await shop.getCart();

// Add to cart
await shop.addToCart({
  product_id: 'prod_123',
  variant_id: 'var_456',  // Optional
  quantity: 2,
});

// Update quantity
await shop.updateCartItem({
  product_id: 'prod_123',
  quantity: 3,
});

// Remove from cart
await shop.removeFromCart({
  product_id: 'prod_123',
});

// Clear cart
await shop.clearCart();

Discounts

// Validate discount code
const validation = await shop.validateDiscount('SAVE10');
if (validation.valid) {
  console.log(`Discount: ${validation.discount_value}% off`);
}

// Apply discount to cart
const cart = await shop.applyDiscount('SAVE10');

Shipping

const rates = await shop.getShippingRates({
  country: 'US',
  state: 'CA',
  postal_code: '90210',
  cart_total: 99.99,
});

Checkout

// Create order (manual payment handling)
const order = await shop.createOrder({
  customer_email: '[email protected]',
  shipping_address: { ... },
});

// Stripe checkout
const stripe = await shop.createStripeCheckout({
  customer_email: '[email protected]',
  shipping_address: { ... },
  success_url: 'https://mysite.com/success',
  cancel_url: 'https://mysite.com/cancel',
});
window.location.href = stripe.data.checkout_url;

// PayPal checkout
const paypal = await shop.createPayPalCheckout({
  customer_email: '[email protected]',
  shipping_address: { ... },
});
window.location.href = paypal.data.approval_url;

Analytics

// Track page view
await shop.trackPageView();

// Track product view
await shop.trackProductView('prod_123');

// Track custom event
await shop.trackEvent({
  event_type: 'add_to_cart',
  product_id: 'prod_123',
  metadata: { source: 'product_page' },
});

Session Management

// Get session ID
const sessionId = shop.getSessionId();

// Set custom session ID (for SSR)
shop.setSessionId('custom-session-id');

Error Handling

import { OrbioShopClient, OrbioShopError } from '@orbiocloud/shop-sdk';

try {
  await shop.addToCart({ product_id: 'invalid' });
} catch (error) {
  if (error instanceof OrbioShopError) {
    console.error(`Error: ${error.message}`);
    console.error(`Code: ${error.code}`);
    console.error(`Status: ${error.status}`);
  }
}

TypeScript

The SDK is written in TypeScript and includes full type definitions:

import type { Product, Cart, CheckoutParams } from '@orbiocloud/shop-sdk';

const product: Product = await shop.getProduct('slug');
const cart: Cart = await shop.getCart();

const checkoutParams: CheckoutParams = {
  customer_email: '[email protected]',
  shipping_address: { ... },
};

License

MIT