arky-sdk 0.3.27 → 0.3.29

package/README.md

@@ -1,6 +1,29 @@
 # arky-sdk
 
-Official TypeScript SDK for Arky - All-in-one business platform
+Official TypeScript SDK for [Arky](https://arky.io) — Build online businesses with headless CMS, e-commerce, and booking systems.
+
+## What is Arky?
+
+Arky is an **all-in-one platform** that gives you everything you need to run an online business:
+
+- 📝 **Headless CMS** - Manage content with flexible blocks, multilingual support, and AI-powered content generation
+- 🛒 **E-commerce** - Sell products with multi-currency pricing, inventory, orders, and Stripe payments
+- 📅 **Booking System** - Manage services, providers, and reservations with availability calendars
+- 📧 **Newsletters** - Send newsletters to subscribers with built-in email delivery
+- 👥 **User Management** - Authentication, roles, permissions, and user profiles
+- 📊 **Analytics** - Track business metrics and performance
+- 💳 **Payments** - Integrated Stripe checkout and promo codes
+
+**Build any online business:** SaaS products, e-commerce stores, booking platforms, content sites, newsletters, or multi-tenant marketplaces.
+
+## Why Use This SDK?
+
+Instead of manually calling REST APIs, use this TypeScript SDK to:
+
+✅ **Type-safe** - Full TypeScript support with IntelliSense  
+✅ **Auto-authentication** - Handles tokens, refresh, and guest sessions automatically  
+✅ **Utility helpers** - Extract block values, format prices, slugify text, validate phones  
+✅ **Framework-agnostic** - Works in React, Vue, Svelte, Node.js, or any JS environment  
 
 ## Installation
 
@@ -10,13 +33,14 @@ npm install arky-sdk
 
 ## Quick Start
 
+### 1. Install & Initialize
+
 ```typescript
 import { createArkySDK } from 'arky-sdk'
 
 const arky = createArkySDK({
   baseUrl: 'https://api.arky.io',
   businessId: 'your-business-id',
-  storageUrl: 'https://storage.arky.io',
   market: 'us',
   getToken: () => ({
     accessToken: localStorage.getItem('accessToken') || '',
@@ -32,12 +56,100 @@ const arky = createArkySDK({
     localStorage.removeItem('accessToken');
     localStorage.removeItem('refreshToken');
   },
-  isAuthenticated: () => !!localStorage.getItem('accessToken'),
 })
+```
+
+### 2. Browse Products
+
+```typescript
+// List products (like on arky.io/products)
+const { items: products } = await arky.eshop.getProducts({
+  limit: 20
+});
+
+// Get product details (like arky.io/products/guitar)
+const product = await arky.eshop.getProduct({ id: 'prod_123' });
+
+// Get price for user's market
+const price = arky.utils.getMarketPrice(product.variants[0].prices, 'US');
+console.log(`${arky.utils.formatMinor(price.amount, price.currency)}`); // "$29.99"
+```
+
+### 3. Shop & Checkout
+
+```typescript
+// Add to cart and checkout (like arky.io/cart)
+const order = await arky.eshop.checkout({
+  items: [{
+    productId: 'prod_123',
+    variantId: 'var_456',
+    quantity: 2
+  }],
+  paymentMethod: 'CREDIT_CARD',
+  shippingMethodId: 'standard',
+  blocks: [  // Customer info
+    { key: 'email', values: ['customer@example.com'] },
+    { key: 'shipping_address', values: ['123 Main St'] }
+  ]
+});
+```
 
-// Now use the SDK
-const collections = await arky.cms.getCollections({});
-const products = await arky.eshop.getProducts({});
+### 4. Book Services
+
+```typescript
+// Browse services (like arky.io/services)
+const { items: services } = await arky.reservation.getServices({});
+
+// Check available time slots
+const slots = await arky.reservation.getAvailableSlots({
+  serviceId: 'service_haircut',
+  from: Date.now(),
+  to: Date.now() + 86400000  // Next 24 hours
+});
+
+// Book a reservation
+const reservation = await arky.reservation.checkout({
+  parts: [{
+    serviceId: 'service_haircut',
+    startTime: slots[0].startTime,
+    providerId: 'provider_jane'
+  }],
+  paymentMethod: 'CREDIT_CARD',
+  blocks: [  // Customer contact info
+    { key: 'name', values: ['John Doe'] },
+    { key: 'phone', values: ['+1234567890'] }
+  ]
+});
+```
+
+### 5. Subscribe to Newsletter
+
+```typescript
+// Subscribe to updates (like arky.io/newsletters)
+await arky.cms.subscribeToCollection({
+  collectionId: 'newsletter_weekly',
+  email: 'user@example.com',
+  planId: 'plan_free'
+});
+```
+
+### 6. Read Content
+
+```typescript
+// Fetch blog posts or content
+const { items: posts } = await arky.cms.getCollectionEntries({
+  collectionId: 'blog',
+  limit: 10
+});
+
+// Extract content from blocks
+const title = arky.utils.getBlockTextValue(
+  posts[0].blocks.find(b => b.key === 'title'),
+  'en'
+);
+const imageUrl = arky.utils.getImageUrl(
+  posts[0].blocks.find(b => b.key === 'featured_image')
+);
 ```
 
 ## API Methods
@@ -245,25 +357,14 @@ const svg = await arky.utils.getSvgContentForAstro(mediaBlock)
 await arky.utils.injectSvgIntoElement(mediaBlock, element, 'custom-class')
 ```
 
-## Features
-
-- 🚀 **TypeScript-first** - Full type safety and IntelliSense
-- 📦 **Tree-shakeable** - Import only what you need
-- ⚡ **Lightweight** - Minimal bundle size (~120KB)
-- 🔄 **Auto-refresh** - Automatic token refresh
-- 🎯 **Framework-agnostic** - Works with any JavaScript framework
-
-## Modules
-
-- **CMS** - Headless content management, newsletters, AI blocks
-- **E-shop** - E-commerce, products, orders, checkout
-- **Reservations** - Booking system, services, providers
-- **Business** - Multi-tenant business management
-- **User** - Authentication, profiles, roles
-- **Media** - File upload, image management
-- **Notifications** - Push, email, SMS
-- **Analytics** - Business metrics and insights
-- **Payment** - Stripe integration, quotes
+## What Can You Build?
+
+- 🏪 **E-commerce stores** - Product catalogs, shopping carts, checkout
+- 📰 **Content websites** - Blogs, documentation, marketing sites
+- 📅 **Booking platforms** - Appointment scheduling, service bookings
+- 📬 **Newsletter platforms** - Subscriber management, email campaigns
+- 🏢 **SaaS products** - Multi-tenant apps with user auth and billing
+- 🛍️ **Marketplaces** - Multi-vendor platforms with payments
 
 ## Configuration Options
 

package/dist/index.cjs

@@ -104,6 +104,7 @@ function createHttpClient(cfg) {
     const fullUrl = `${cfg.baseUrl}${finalPath}`;
     let res;
     let data;
+    const startedAt = Date.now();
     try {
       res = await fetch(fullUrl, fetchOpts);
     } catch (error) {
@@ -111,6 +112,12 @@ function createHttpClient(cfg) {
       err.name = "NetworkError";
       err.method = method;
       err.url = fullUrl;
+      if (options?.onError && method !== "GET") {
+        Promise.resolve(
+          options.onError({ error: err, method, url: fullUrl, aborted: false })
+        ).catch(() => {
+        });
+      }
       throw err;
     }
     if (res.status === 401 && !options?.["_retried"]) {
@@ -137,14 +144,17 @@ function createHttpClient(cfg) {
       err.method = method;
       err.url = fullUrl;
       err.status = res.status;
+      if (options?.onError && method !== "GET") {
+        Promise.resolve(
+          options.onError({ error: err, method, url: fullUrl, status: res.status })
+        ).catch(() => {
+        });
+      }
       throw err;
     }
     if (!res.ok) {
       const serverErr = data;
       const reqErr = convertServerErrorToRequestError(serverErr);
-      if (options?.errorMessage && cfg.notify) {
-        cfg.notify({ message: options.errorMessage, type: "error" });
-      }
       const err = new Error(serverErr.message || "Request failed");
       err.name = "ApiError";
       err.statusCode = serverErr.statusCode || res.status;
@@ -153,10 +163,35 @@ function createHttpClient(cfg) {
       err.url = fullUrl;
       const requestId = res.headers.get("x-request-id") || res.headers.get("request-id");
       if (requestId) err.requestId = requestId;
+      if (options?.onError && method !== "GET") {
+        Promise.resolve(
+          options.onError({
+            error: err,
+            method,
+            url: fullUrl,
+            status: res.status,
+            response: serverErr,
+            requestId: requestId || null,
+            durationMs: Date.now() - startedAt
+          })
+        ).catch(() => {
+        });
+      }
       throw err;
     }
-    if (options?.successMessage && cfg.notify) {
-      cfg.notify({ message: options.successMessage, type: "success" });
+    if (options?.onSuccess && method !== "GET") {
+      const requestId = res.headers.get("x-request-id") || res.headers.get("request-id");
+      Promise.resolve(
+        options.onSuccess({
+          data,
+          method,
+          url: fullUrl,
+          status: res.status,
+          requestId: requestId || null,
+          durationMs: Date.now() - startedAt
+        })
+      ).catch(() => {
+      });
     }
     return data;
   }
@@ -417,18 +452,6 @@ var createRoleApi = (apiConfig) => {
 // src/api/notification.ts
 var createNotificationApi = (apiConfig) => {
   return {
-    async getNotifications(params, options) {
-      return apiConfig.httpClient.get(`/v1/notifications`, {
-        ...options,
-        params: {
-          limit: params.limit,
-          previous_id: params.previous_id
-        }
-      });
-    },
-    async updateNotifications(params, options) {
-      return apiConfig.httpClient.put(`/v1/notifications`, { seen: true }, options);
-    },
     async trackEmailOpen(params, options) {
       return apiConfig.httpClient.get(
         `/v1/notifications/track/email/${params.trackingPixelId}`,
@@ -490,12 +513,6 @@ var createAnalyticsApi = (apiConfig) => {
         ...options,
         params
       });
-    },
-    async getAnalyticsHealth(params, options) {
-      return apiConfig.httpClient.get(`/v1/analytics/${apiConfig.businessId}/health`, options);
-    },
-    async setupAnalytics(params, options) {
-      return apiConfig.httpClient.post(`/v1/analytics/admin/setup`, params, options);
     }
   };
 };
@@ -1123,16 +1140,6 @@ var getImageUrl = (imageBlock, isBlock = true, storageUrl = "https://storage.ark
   }
   return null;
 };
-function getGalleryThumbnail(gallery) {
-  if (!gallery?.length) return null;
-  const item = gallery.find((g) => g.settings.isThumbnail) || gallery[0];
-  const res = item.media.resolutions.thumbnail || item.media.resolutions.original;
-  return res?.url || null;
-}
-function thumbnailUrl(service, storageUrl = "") {
-  const path = getGalleryThumbnail(service.gallery);
-  return path ? `${storageUrl}/${path}` : null;
-}
 
 // src/utils/currency.ts
 function getCurrencySymbol(currency) {
@@ -1482,7 +1489,7 @@ async function injectSvgIntoElement(mediaObject, targetElement, className) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.3.25";
+var SDK_VERSION = "0.3.28";
 var SUPPORTED_FRAMEWORKS = [
   "astro",
   "react",
@@ -1533,8 +1540,6 @@ function createArkySDK(config) {
     utils: {
       // Block utilities
       getImageUrl: (imageBlock, isBlock = true) => getImageUrl(imageBlock, isBlock, storageUrl),
-      thumbnailUrl: (service) => thumbnailUrl(service, storageUrl),
-      getGalleryThumbnail,
       getBlockValue,
       getBlockValues,
       getBlockLabel,