omni-sync-sdk 0.6.2 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -17
- package/dist/index.d.mts +70 -5
- package/dist/index.d.ts +70 -5
- package/dist/index.js +119 -4
- package/dist/index.mjs +119 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -256,23 +256,24 @@ interface InventoryInfo {
|
|
|
256
256
|
|
|
257
257
|
```tsx
|
|
258
258
|
// Correct way to render product descriptions
|
|
259
|
-
{
|
|
260
|
-
product.
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
)
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
|
273
|
-
|
|
|
274
|
-
|
|
|
275
|
-
|
|
|
259
|
+
{
|
|
260
|
+
product.description &&
|
|
261
|
+
(product.descriptionFormat === 'html' ? (
|
|
262
|
+
// HTML content from Shopify/WooCommerce - render as HTML
|
|
263
|
+
<div dangerouslySetInnerHTML={{ __html: product.description }} />
|
|
264
|
+
) : (
|
|
265
|
+
// Plain text - render normally
|
|
266
|
+
<p>{product.description}</p>
|
|
267
|
+
));
|
|
268
|
+
}
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
| Source Platform | descriptionFormat | Rendering |
|
|
272
|
+
| --------------- | ----------------- | ----------------------------- |
|
|
273
|
+
| Shopify | `'html'` | Use `dangerouslySetInnerHTML` |
|
|
274
|
+
| WooCommerce | `'html'` | Use `dangerouslySetInnerHTML` |
|
|
275
|
+
| TikTok | `'text'` | Render as plain text |
|
|
276
|
+
| Manual entry | `'text'` | Render as plain text |
|
|
276
277
|
|
|
277
278
|
---
|
|
278
279
|
|
|
@@ -448,6 +449,8 @@ console.log(order.message); // 'Order created successfully'
|
|
|
448
449
|
// Cart is automatically cleared after successful order
|
|
449
450
|
```
|
|
450
451
|
|
|
452
|
+
> **🔄 Automatic Tracking:** If "Track Guest Checkouts" is enabled in your connection settings (OmniSync Admin), `submitGuestOrder()` will automatically create a tracked checkout session before placing the order. This allows you to see abandoned carts and checkout sessions in your admin dashboard - **no code changes needed!**
|
|
453
|
+
|
|
451
454
|
#### Keep Cart After Order
|
|
452
455
|
|
|
453
456
|
```typescript
|
|
@@ -497,6 +500,71 @@ interface GuestOrderResponse {
|
|
|
497
500
|
|
|
498
501
|
---
|
|
499
502
|
|
|
503
|
+
### Tracked Guest Checkout (Automatic)
|
|
504
|
+
|
|
505
|
+
> **Note:** As of SDK v0.7.1, `submitGuestOrder()` automatically handles tracking. You don't need to use these methods unless you want explicit control over the checkout flow.
|
|
506
|
+
|
|
507
|
+
When **"Track Guest Checkouts"** is enabled in your connection settings, checkout sessions are automatically created on the server, allowing:
|
|
508
|
+
|
|
509
|
+
- Visibility of checkout sessions in admin dashboard
|
|
510
|
+
- Abandoned cart tracking
|
|
511
|
+
- Future: abandoned cart recovery emails
|
|
512
|
+
|
|
513
|
+
#### How to Enable
|
|
514
|
+
|
|
515
|
+
1. Go to OmniSync Admin → Integrations → Vibe-Coded Sites
|
|
516
|
+
2. Click on your connection → Settings
|
|
517
|
+
3. Enable "Track Guest Checkouts"
|
|
518
|
+
4. Save - that's it! No code changes needed.
|
|
519
|
+
|
|
520
|
+
#### Advanced: Manual Tracking Control
|
|
521
|
+
|
|
522
|
+
If you need explicit control over the tracking flow (e.g., to track checkout steps before the user places an order):
|
|
523
|
+
|
|
524
|
+
```typescript
|
|
525
|
+
// 1. Start tracked checkout (sends cart items to server)
|
|
526
|
+
const checkout = await omni.startGuestCheckout();
|
|
527
|
+
|
|
528
|
+
if (checkout.tracked) {
|
|
529
|
+
// 2. Update with shipping address
|
|
530
|
+
await omni.updateGuestCheckoutAddress(checkout.checkoutId, {
|
|
531
|
+
shippingAddress: {
|
|
532
|
+
firstName: 'John',
|
|
533
|
+
lastName: 'Doe',
|
|
534
|
+
line1: '123 Main St',
|
|
535
|
+
city: 'New York',
|
|
536
|
+
postalCode: '10001',
|
|
537
|
+
country: 'US',
|
|
538
|
+
},
|
|
539
|
+
});
|
|
540
|
+
|
|
541
|
+
// 3. Complete the checkout
|
|
542
|
+
const order = await omni.completeGuestCheckout(checkout.checkoutId);
|
|
543
|
+
console.log('Order created:', order.orderId);
|
|
544
|
+
} else {
|
|
545
|
+
// Fallback to regular guest checkout
|
|
546
|
+
const order = await omni.submitGuestOrder();
|
|
547
|
+
}
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
#### Response Types
|
|
551
|
+
|
|
552
|
+
```typescript
|
|
553
|
+
type GuestCheckoutStartResponse =
|
|
554
|
+
| {
|
|
555
|
+
tracked: true;
|
|
556
|
+
checkoutId: string;
|
|
557
|
+
cartId: string;
|
|
558
|
+
message: string;
|
|
559
|
+
}
|
|
560
|
+
| {
|
|
561
|
+
tracked: false;
|
|
562
|
+
message: string;
|
|
563
|
+
};
|
|
564
|
+
```
|
|
565
|
+
|
|
566
|
+
---
|
|
567
|
+
|
|
500
568
|
### Server Cart (Registered Users)
|
|
501
569
|
|
|
502
570
|
For logged-in customers who want cart sync across devices.
|
package/dist/index.d.mts
CHANGED
|
@@ -640,6 +640,20 @@ interface GuestOrderResponse {
|
|
|
640
640
|
total: number;
|
|
641
641
|
message: string;
|
|
642
642
|
}
|
|
643
|
+
/**
|
|
644
|
+
* Response from starting a tracked guest checkout session
|
|
645
|
+
* If tracking is enabled, returns checkoutId and cartId
|
|
646
|
+
* If tracking is not enabled, returns tracked: false
|
|
647
|
+
*/
|
|
648
|
+
type GuestCheckoutStartResponse = {
|
|
649
|
+
tracked: true;
|
|
650
|
+
checkoutId: string;
|
|
651
|
+
cartId: string;
|
|
652
|
+
message: string;
|
|
653
|
+
} | {
|
|
654
|
+
tracked: false;
|
|
655
|
+
message: string;
|
|
656
|
+
};
|
|
643
657
|
type CheckoutStatus = 'PENDING' | 'SHIPPING_SET' | 'PAYMENT_PENDING' | 'PAYMENT_PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED';
|
|
644
658
|
interface CheckoutAddress {
|
|
645
659
|
firstName: string;
|
|
@@ -1969,7 +1983,10 @@ declare class OmniSyncClient {
|
|
|
1969
1983
|
/**
|
|
1970
1984
|
* Create order directly from local cart (guest checkout)
|
|
1971
1985
|
* This is the main checkout method for vibe-coded sites!
|
|
1972
|
-
*
|
|
1986
|
+
*
|
|
1987
|
+
* **Automatic Tracking:** If "Track Guest Checkouts" is enabled in the connection
|
|
1988
|
+
* settings, this method will automatically create a tracked checkout session
|
|
1989
|
+
* (visible in admin) before creating the order. No code changes needed!
|
|
1973
1990
|
*
|
|
1974
1991
|
* @example
|
|
1975
1992
|
* ```typescript
|
|
@@ -1978,17 +1995,65 @@ declare class OmniSyncClient {
|
|
|
1978
1995
|
* omni.setLocalCartCustomer({ email: 'john@example.com', firstName: 'John' });
|
|
1979
1996
|
* omni.setLocalCartShippingAddress({ ... });
|
|
1980
1997
|
*
|
|
1981
|
-
* // Then submit the order
|
|
1998
|
+
* // Then submit the order - tracking is automatic if enabled in admin!
|
|
1982
1999
|
* const result = await omni.submitGuestOrder();
|
|
1983
2000
|
* console.log('Order created:', result.orderId);
|
|
1984
2001
|
*
|
|
1985
|
-
* //
|
|
1986
|
-
* omni.clearLocalCart();
|
|
2002
|
+
* // Cart is automatically cleared on success
|
|
1987
2003
|
* ```
|
|
1988
2004
|
*/
|
|
1989
2005
|
submitGuestOrder(options?: {
|
|
1990
2006
|
clearCartOnSuccess?: boolean;
|
|
1991
2007
|
}): Promise<GuestOrderResponse>;
|
|
2008
|
+
/**
|
|
2009
|
+
* Start a tracked guest checkout session (if enabled on connection)
|
|
2010
|
+
*
|
|
2011
|
+
* This creates Cart + Checkout records on the server so the store admin
|
|
2012
|
+
* can see checkout sessions and track abandoned carts.
|
|
2013
|
+
*
|
|
2014
|
+
* If tracking is not enabled for this connection, returns { tracked: false }.
|
|
2015
|
+
* If tracking is enabled, returns { tracked: true, checkoutId, cartId }.
|
|
2016
|
+
*
|
|
2017
|
+
* @example
|
|
2018
|
+
* ```typescript
|
|
2019
|
+
* // When customer goes to checkout page
|
|
2020
|
+
* const result = await omni.startGuestCheckout();
|
|
2021
|
+
*
|
|
2022
|
+
* if (result.tracked) {
|
|
2023
|
+
* // Store checkoutId for later use
|
|
2024
|
+
* console.log('Checkout tracked:', result.checkoutId);
|
|
2025
|
+
*
|
|
2026
|
+
* // Update checkout with address
|
|
2027
|
+
* await omni.updateGuestCheckout(result.checkoutId, {
|
|
2028
|
+
* shippingAddress: { ... },
|
|
2029
|
+
* });
|
|
2030
|
+
*
|
|
2031
|
+
* // Complete checkout
|
|
2032
|
+
* const order = await omni.completeGuestCheckout(result.checkoutId);
|
|
2033
|
+
* } else {
|
|
2034
|
+
* // Tracking not enabled, use regular submitGuestOrder
|
|
2035
|
+
* const order = await omni.submitGuestOrder();
|
|
2036
|
+
* }
|
|
2037
|
+
* ```
|
|
2038
|
+
*/
|
|
2039
|
+
startGuestCheckout(): Promise<GuestCheckoutStartResponse>;
|
|
2040
|
+
/**
|
|
2041
|
+
* Update a tracked guest checkout with shipping/billing address
|
|
2042
|
+
* Use after startGuestCheckout() returns { tracked: true }
|
|
2043
|
+
*/
|
|
2044
|
+
updateGuestCheckoutAddress(checkoutId: string, data: {
|
|
2045
|
+
shippingAddress?: SetShippingAddressDto;
|
|
2046
|
+
billingAddress?: SetBillingAddressDto;
|
|
2047
|
+
}): Promise<Checkout>;
|
|
2048
|
+
/**
|
|
2049
|
+
* Complete a tracked guest checkout - creates the order
|
|
2050
|
+
* Use after startGuestCheckout() and updateGuestCheckoutAddress()
|
|
2051
|
+
*/
|
|
2052
|
+
completeGuestCheckout(checkoutId: string, options?: {
|
|
2053
|
+
clearCartOnSuccess?: boolean;
|
|
2054
|
+
}): Promise<{
|
|
2055
|
+
orderId: string;
|
|
2056
|
+
}>;
|
|
1992
2057
|
/**
|
|
1993
2058
|
* Create order from custom data (not from local cart)
|
|
1994
2059
|
* Use this if you manage cart state yourself
|
|
@@ -2212,4 +2277,4 @@ declare function isWebhookEventType(event: WebhookEvent, type: WebhookEventType)
|
|
|
2212
2277
|
*/
|
|
2213
2278
|
declare function createWebhookHandler(handlers: Partial<Record<WebhookEventType, (event: WebhookEvent) => Promise<void>>>): (payload: unknown) => Promise<void>;
|
|
2214
2279
|
|
|
2215
|
-
export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConnectorPlatform, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateCheckoutDto, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateGuestOrderDto, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type FulfillOrderDto, type GuestOrderResponse, type InventoryInfo, type InventorySyncStatus, type LocalCart, type LocalCartItem, type MergeCartsDto, type OmniSyncApiError, OmniSyncClient, type OmniSyncClientOptions, OmniSyncError, type Order, type OrderAddress, type OrderCustomer, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PlatformCouponCapabilities, type Product, type ProductAttributeInput, type ProductImage, type ProductQueryParams, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SelectShippingMethodDto, type SendInvoiceDto, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingLine, type ShippingRate, type StoreInfo, type SyncJob, type UpdateAddressDto, type UpdateCartItemDto, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateInventoryDto, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateVariantDto, type UpdateVariantInventoryDto, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WebhookEvent, type WebhookEventType, createWebhookHandler, isCouponApplicableToProduct, isWebhookEventType, parseWebhookEvent, verifyWebhook };
|
|
2280
|
+
export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConnectorPlatform, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateCheckoutDto, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateGuestOrderDto, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InventoryInfo, type InventorySyncStatus, type LocalCart, type LocalCartItem, type MergeCartsDto, type OmniSyncApiError, OmniSyncClient, type OmniSyncClientOptions, OmniSyncError, type Order, type OrderAddress, type OrderCustomer, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PlatformCouponCapabilities, type Product, type ProductAttributeInput, type ProductImage, type ProductQueryParams, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SelectShippingMethodDto, type SendInvoiceDto, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingLine, type ShippingRate, type StoreInfo, type SyncJob, type UpdateAddressDto, type UpdateCartItemDto, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateInventoryDto, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateVariantDto, type UpdateVariantInventoryDto, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WebhookEvent, type WebhookEventType, createWebhookHandler, isCouponApplicableToProduct, isWebhookEventType, parseWebhookEvent, verifyWebhook };
|
package/dist/index.d.ts
CHANGED
|
@@ -640,6 +640,20 @@ interface GuestOrderResponse {
|
|
|
640
640
|
total: number;
|
|
641
641
|
message: string;
|
|
642
642
|
}
|
|
643
|
+
/**
|
|
644
|
+
* Response from starting a tracked guest checkout session
|
|
645
|
+
* If tracking is enabled, returns checkoutId and cartId
|
|
646
|
+
* If tracking is not enabled, returns tracked: false
|
|
647
|
+
*/
|
|
648
|
+
type GuestCheckoutStartResponse = {
|
|
649
|
+
tracked: true;
|
|
650
|
+
checkoutId: string;
|
|
651
|
+
cartId: string;
|
|
652
|
+
message: string;
|
|
653
|
+
} | {
|
|
654
|
+
tracked: false;
|
|
655
|
+
message: string;
|
|
656
|
+
};
|
|
643
657
|
type CheckoutStatus = 'PENDING' | 'SHIPPING_SET' | 'PAYMENT_PENDING' | 'PAYMENT_PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED';
|
|
644
658
|
interface CheckoutAddress {
|
|
645
659
|
firstName: string;
|
|
@@ -1969,7 +1983,10 @@ declare class OmniSyncClient {
|
|
|
1969
1983
|
/**
|
|
1970
1984
|
* Create order directly from local cart (guest checkout)
|
|
1971
1985
|
* This is the main checkout method for vibe-coded sites!
|
|
1972
|
-
*
|
|
1986
|
+
*
|
|
1987
|
+
* **Automatic Tracking:** If "Track Guest Checkouts" is enabled in the connection
|
|
1988
|
+
* settings, this method will automatically create a tracked checkout session
|
|
1989
|
+
* (visible in admin) before creating the order. No code changes needed!
|
|
1973
1990
|
*
|
|
1974
1991
|
* @example
|
|
1975
1992
|
* ```typescript
|
|
@@ -1978,17 +1995,65 @@ declare class OmniSyncClient {
|
|
|
1978
1995
|
* omni.setLocalCartCustomer({ email: 'john@example.com', firstName: 'John' });
|
|
1979
1996
|
* omni.setLocalCartShippingAddress({ ... });
|
|
1980
1997
|
*
|
|
1981
|
-
* // Then submit the order
|
|
1998
|
+
* // Then submit the order - tracking is automatic if enabled in admin!
|
|
1982
1999
|
* const result = await omni.submitGuestOrder();
|
|
1983
2000
|
* console.log('Order created:', result.orderId);
|
|
1984
2001
|
*
|
|
1985
|
-
* //
|
|
1986
|
-
* omni.clearLocalCart();
|
|
2002
|
+
* // Cart is automatically cleared on success
|
|
1987
2003
|
* ```
|
|
1988
2004
|
*/
|
|
1989
2005
|
submitGuestOrder(options?: {
|
|
1990
2006
|
clearCartOnSuccess?: boolean;
|
|
1991
2007
|
}): Promise<GuestOrderResponse>;
|
|
2008
|
+
/**
|
|
2009
|
+
* Start a tracked guest checkout session (if enabled on connection)
|
|
2010
|
+
*
|
|
2011
|
+
* This creates Cart + Checkout records on the server so the store admin
|
|
2012
|
+
* can see checkout sessions and track abandoned carts.
|
|
2013
|
+
*
|
|
2014
|
+
* If tracking is not enabled for this connection, returns { tracked: false }.
|
|
2015
|
+
* If tracking is enabled, returns { tracked: true, checkoutId, cartId }.
|
|
2016
|
+
*
|
|
2017
|
+
* @example
|
|
2018
|
+
* ```typescript
|
|
2019
|
+
* // When customer goes to checkout page
|
|
2020
|
+
* const result = await omni.startGuestCheckout();
|
|
2021
|
+
*
|
|
2022
|
+
* if (result.tracked) {
|
|
2023
|
+
* // Store checkoutId for later use
|
|
2024
|
+
* console.log('Checkout tracked:', result.checkoutId);
|
|
2025
|
+
*
|
|
2026
|
+
* // Update checkout with address
|
|
2027
|
+
* await omni.updateGuestCheckout(result.checkoutId, {
|
|
2028
|
+
* shippingAddress: { ... },
|
|
2029
|
+
* });
|
|
2030
|
+
*
|
|
2031
|
+
* // Complete checkout
|
|
2032
|
+
* const order = await omni.completeGuestCheckout(result.checkoutId);
|
|
2033
|
+
* } else {
|
|
2034
|
+
* // Tracking not enabled, use regular submitGuestOrder
|
|
2035
|
+
* const order = await omni.submitGuestOrder();
|
|
2036
|
+
* }
|
|
2037
|
+
* ```
|
|
2038
|
+
*/
|
|
2039
|
+
startGuestCheckout(): Promise<GuestCheckoutStartResponse>;
|
|
2040
|
+
/**
|
|
2041
|
+
* Update a tracked guest checkout with shipping/billing address
|
|
2042
|
+
* Use after startGuestCheckout() returns { tracked: true }
|
|
2043
|
+
*/
|
|
2044
|
+
updateGuestCheckoutAddress(checkoutId: string, data: {
|
|
2045
|
+
shippingAddress?: SetShippingAddressDto;
|
|
2046
|
+
billingAddress?: SetBillingAddressDto;
|
|
2047
|
+
}): Promise<Checkout>;
|
|
2048
|
+
/**
|
|
2049
|
+
* Complete a tracked guest checkout - creates the order
|
|
2050
|
+
* Use after startGuestCheckout() and updateGuestCheckoutAddress()
|
|
2051
|
+
*/
|
|
2052
|
+
completeGuestCheckout(checkoutId: string, options?: {
|
|
2053
|
+
clearCartOnSuccess?: boolean;
|
|
2054
|
+
}): Promise<{
|
|
2055
|
+
orderId: string;
|
|
2056
|
+
}>;
|
|
1992
2057
|
/**
|
|
1993
2058
|
* Create order from custom data (not from local cart)
|
|
1994
2059
|
* Use this if you manage cart state yourself
|
|
@@ -2212,4 +2277,4 @@ declare function isWebhookEventType(event: WebhookEvent, type: WebhookEventType)
|
|
|
2212
2277
|
*/
|
|
2213
2278
|
declare function createWebhookHandler(handlers: Partial<Record<WebhookEventType, (event: WebhookEvent) => Promise<void>>>): (payload: unknown) => Promise<void>;
|
|
2214
2279
|
|
|
2215
|
-
export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConnectorPlatform, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateCheckoutDto, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateGuestOrderDto, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type FulfillOrderDto, type GuestOrderResponse, type InventoryInfo, type InventorySyncStatus, type LocalCart, type LocalCartItem, type MergeCartsDto, type OmniSyncApiError, OmniSyncClient, type OmniSyncClientOptions, OmniSyncError, type Order, type OrderAddress, type OrderCustomer, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PlatformCouponCapabilities, type Product, type ProductAttributeInput, type ProductImage, type ProductQueryParams, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SelectShippingMethodDto, type SendInvoiceDto, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingLine, type ShippingRate, type StoreInfo, type SyncJob, type UpdateAddressDto, type UpdateCartItemDto, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateInventoryDto, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateVariantDto, type UpdateVariantInventoryDto, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WebhookEvent, type WebhookEventType, createWebhookHandler, isCouponApplicableToProduct, isWebhookEventType, parseWebhookEvent, verifyWebhook };
|
|
2280
|
+
export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConnectorPlatform, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateCheckoutDto, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateGuestOrderDto, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InventoryInfo, type InventorySyncStatus, type LocalCart, type LocalCartItem, type MergeCartsDto, type OmniSyncApiError, OmniSyncClient, type OmniSyncClientOptions, OmniSyncError, type Order, type OrderAddress, type OrderCustomer, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PlatformCouponCapabilities, type Product, type ProductAttributeInput, type ProductImage, type ProductQueryParams, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SelectShippingMethodDto, type SendInvoiceDto, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingLine, type ShippingRate, type StoreInfo, type SyncJob, type UpdateAddressDto, type UpdateCartItemDto, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateInventoryDto, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateVariantDto, type UpdateVariantInventoryDto, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WebhookEvent, type WebhookEventType, createWebhookHandler, isCouponApplicableToProduct, isWebhookEventType, parseWebhookEvent, verifyWebhook };
|
package/dist/index.js
CHANGED
|
@@ -1705,7 +1705,10 @@ var OmniSyncClient = class {
|
|
|
1705
1705
|
/**
|
|
1706
1706
|
* Create order directly from local cart (guest checkout)
|
|
1707
1707
|
* This is the main checkout method for vibe-coded sites!
|
|
1708
|
-
*
|
|
1708
|
+
*
|
|
1709
|
+
* **Automatic Tracking:** If "Track Guest Checkouts" is enabled in the connection
|
|
1710
|
+
* settings, this method will automatically create a tracked checkout session
|
|
1711
|
+
* (visible in admin) before creating the order. No code changes needed!
|
|
1709
1712
|
*
|
|
1710
1713
|
* @example
|
|
1711
1714
|
* ```typescript
|
|
@@ -1714,12 +1717,11 @@ var OmniSyncClient = class {
|
|
|
1714
1717
|
* omni.setLocalCartCustomer({ email: 'john@example.com', firstName: 'John' });
|
|
1715
1718
|
* omni.setLocalCartShippingAddress({ ... });
|
|
1716
1719
|
*
|
|
1717
|
-
* // Then submit the order
|
|
1720
|
+
* // Then submit the order - tracking is automatic if enabled in admin!
|
|
1718
1721
|
* const result = await omni.submitGuestOrder();
|
|
1719
1722
|
* console.log('Order created:', result.orderId);
|
|
1720
1723
|
*
|
|
1721
|
-
* //
|
|
1722
|
-
* omni.clearLocalCart();
|
|
1724
|
+
* // Cart is automatically cleared on success
|
|
1723
1725
|
* ```
|
|
1724
1726
|
*/
|
|
1725
1727
|
async submitGuestOrder(options) {
|
|
@@ -1733,6 +1735,28 @@ var OmniSyncClient = class {
|
|
|
1733
1735
|
if (!cart.shippingAddress) {
|
|
1734
1736
|
throw new OmniSyncError("Shipping address is required", 400);
|
|
1735
1737
|
}
|
|
1738
|
+
try {
|
|
1739
|
+
const trackingResult = await this.startGuestCheckout();
|
|
1740
|
+
if (trackingResult.tracked) {
|
|
1741
|
+
await this.updateGuestCheckoutAddress(trackingResult.checkoutId, {
|
|
1742
|
+
shippingAddress: cart.shippingAddress,
|
|
1743
|
+
billingAddress: cart.billingAddress
|
|
1744
|
+
});
|
|
1745
|
+
const orderResult = await this.completeGuestCheckout(trackingResult.checkoutId, {
|
|
1746
|
+
clearCartOnSuccess: options?.clearCartOnSuccess
|
|
1747
|
+
});
|
|
1748
|
+
return {
|
|
1749
|
+
orderId: orderResult.orderId,
|
|
1750
|
+
orderNumber: orderResult.orderId,
|
|
1751
|
+
// Will be overwritten by actual order number if returned
|
|
1752
|
+
status: "pending",
|
|
1753
|
+
total: 0,
|
|
1754
|
+
// Actual total comes from server
|
|
1755
|
+
message: "Order created successfully (tracked)"
|
|
1756
|
+
};
|
|
1757
|
+
}
|
|
1758
|
+
} catch {
|
|
1759
|
+
}
|
|
1736
1760
|
const orderData = {
|
|
1737
1761
|
items: cart.items.map((item) => ({
|
|
1738
1762
|
productId: item.productId,
|
|
@@ -1751,6 +1775,97 @@ var OmniSyncClient = class {
|
|
|
1751
1775
|
}
|
|
1752
1776
|
return result;
|
|
1753
1777
|
}
|
|
1778
|
+
/**
|
|
1779
|
+
* Start a tracked guest checkout session (if enabled on connection)
|
|
1780
|
+
*
|
|
1781
|
+
* This creates Cart + Checkout records on the server so the store admin
|
|
1782
|
+
* can see checkout sessions and track abandoned carts.
|
|
1783
|
+
*
|
|
1784
|
+
* If tracking is not enabled for this connection, returns { tracked: false }.
|
|
1785
|
+
* If tracking is enabled, returns { tracked: true, checkoutId, cartId }.
|
|
1786
|
+
*
|
|
1787
|
+
* @example
|
|
1788
|
+
* ```typescript
|
|
1789
|
+
* // When customer goes to checkout page
|
|
1790
|
+
* const result = await omni.startGuestCheckout();
|
|
1791
|
+
*
|
|
1792
|
+
* if (result.tracked) {
|
|
1793
|
+
* // Store checkoutId for later use
|
|
1794
|
+
* console.log('Checkout tracked:', result.checkoutId);
|
|
1795
|
+
*
|
|
1796
|
+
* // Update checkout with address
|
|
1797
|
+
* await omni.updateGuestCheckout(result.checkoutId, {
|
|
1798
|
+
* shippingAddress: { ... },
|
|
1799
|
+
* });
|
|
1800
|
+
*
|
|
1801
|
+
* // Complete checkout
|
|
1802
|
+
* const order = await omni.completeGuestCheckout(result.checkoutId);
|
|
1803
|
+
* } else {
|
|
1804
|
+
* // Tracking not enabled, use regular submitGuestOrder
|
|
1805
|
+
* const order = await omni.submitGuestOrder();
|
|
1806
|
+
* }
|
|
1807
|
+
* ```
|
|
1808
|
+
*/
|
|
1809
|
+
async startGuestCheckout() {
|
|
1810
|
+
const cart = this.getLocalCart();
|
|
1811
|
+
if (cart.items.length === 0) {
|
|
1812
|
+
throw new OmniSyncError("Cart is empty", 400);
|
|
1813
|
+
}
|
|
1814
|
+
const response = await this.vibeCodedRequest(
|
|
1815
|
+
"POST",
|
|
1816
|
+
"/guest-checkout",
|
|
1817
|
+
{
|
|
1818
|
+
items: cart.items.map((item) => ({
|
|
1819
|
+
productId: item.productId,
|
|
1820
|
+
variantId: item.variantId,
|
|
1821
|
+
quantity: item.quantity
|
|
1822
|
+
})),
|
|
1823
|
+
customer: cart.customer
|
|
1824
|
+
}
|
|
1825
|
+
);
|
|
1826
|
+
return response;
|
|
1827
|
+
}
|
|
1828
|
+
/**
|
|
1829
|
+
* Update a tracked guest checkout with shipping/billing address
|
|
1830
|
+
* Use after startGuestCheckout() returns { tracked: true }
|
|
1831
|
+
*/
|
|
1832
|
+
async updateGuestCheckoutAddress(checkoutId, data) {
|
|
1833
|
+
let checkout = null;
|
|
1834
|
+
if (data.shippingAddress) {
|
|
1835
|
+
const result = await this.vibeCodedRequest(
|
|
1836
|
+
"PATCH",
|
|
1837
|
+
`/checkout/${checkoutId}/shipping-address`,
|
|
1838
|
+
data.shippingAddress
|
|
1839
|
+
);
|
|
1840
|
+
checkout = result.checkout;
|
|
1841
|
+
}
|
|
1842
|
+
if (data.billingAddress) {
|
|
1843
|
+
checkout = await this.vibeCodedRequest(
|
|
1844
|
+
"PATCH",
|
|
1845
|
+
`/checkout/${checkoutId}/billing-address`,
|
|
1846
|
+
data.billingAddress
|
|
1847
|
+
);
|
|
1848
|
+
}
|
|
1849
|
+
if (!checkout) {
|
|
1850
|
+
throw new OmniSyncError("No address data provided", 400);
|
|
1851
|
+
}
|
|
1852
|
+
return checkout;
|
|
1853
|
+
}
|
|
1854
|
+
/**
|
|
1855
|
+
* Complete a tracked guest checkout - creates the order
|
|
1856
|
+
* Use after startGuestCheckout() and updateGuestCheckoutAddress()
|
|
1857
|
+
*/
|
|
1858
|
+
async completeGuestCheckout(checkoutId, options) {
|
|
1859
|
+
const result = await this.vibeCodedRequest(
|
|
1860
|
+
"POST",
|
|
1861
|
+
`/checkout/${checkoutId}/complete`,
|
|
1862
|
+
{}
|
|
1863
|
+
);
|
|
1864
|
+
if (options?.clearCartOnSuccess !== false) {
|
|
1865
|
+
this.clearLocalCart();
|
|
1866
|
+
}
|
|
1867
|
+
return result;
|
|
1868
|
+
}
|
|
1754
1869
|
/**
|
|
1755
1870
|
* Create order from custom data (not from local cart)
|
|
1756
1871
|
* Use this if you manage cart state yourself
|
package/dist/index.mjs
CHANGED
|
@@ -1680,7 +1680,10 @@ var OmniSyncClient = class {
|
|
|
1680
1680
|
/**
|
|
1681
1681
|
* Create order directly from local cart (guest checkout)
|
|
1682
1682
|
* This is the main checkout method for vibe-coded sites!
|
|
1683
|
-
*
|
|
1683
|
+
*
|
|
1684
|
+
* **Automatic Tracking:** If "Track Guest Checkouts" is enabled in the connection
|
|
1685
|
+
* settings, this method will automatically create a tracked checkout session
|
|
1686
|
+
* (visible in admin) before creating the order. No code changes needed!
|
|
1684
1687
|
*
|
|
1685
1688
|
* @example
|
|
1686
1689
|
* ```typescript
|
|
@@ -1689,12 +1692,11 @@ var OmniSyncClient = class {
|
|
|
1689
1692
|
* omni.setLocalCartCustomer({ email: 'john@example.com', firstName: 'John' });
|
|
1690
1693
|
* omni.setLocalCartShippingAddress({ ... });
|
|
1691
1694
|
*
|
|
1692
|
-
* // Then submit the order
|
|
1695
|
+
* // Then submit the order - tracking is automatic if enabled in admin!
|
|
1693
1696
|
* const result = await omni.submitGuestOrder();
|
|
1694
1697
|
* console.log('Order created:', result.orderId);
|
|
1695
1698
|
*
|
|
1696
|
-
* //
|
|
1697
|
-
* omni.clearLocalCart();
|
|
1699
|
+
* // Cart is automatically cleared on success
|
|
1698
1700
|
* ```
|
|
1699
1701
|
*/
|
|
1700
1702
|
async submitGuestOrder(options) {
|
|
@@ -1708,6 +1710,28 @@ var OmniSyncClient = class {
|
|
|
1708
1710
|
if (!cart.shippingAddress) {
|
|
1709
1711
|
throw new OmniSyncError("Shipping address is required", 400);
|
|
1710
1712
|
}
|
|
1713
|
+
try {
|
|
1714
|
+
const trackingResult = await this.startGuestCheckout();
|
|
1715
|
+
if (trackingResult.tracked) {
|
|
1716
|
+
await this.updateGuestCheckoutAddress(trackingResult.checkoutId, {
|
|
1717
|
+
shippingAddress: cart.shippingAddress,
|
|
1718
|
+
billingAddress: cart.billingAddress
|
|
1719
|
+
});
|
|
1720
|
+
const orderResult = await this.completeGuestCheckout(trackingResult.checkoutId, {
|
|
1721
|
+
clearCartOnSuccess: options?.clearCartOnSuccess
|
|
1722
|
+
});
|
|
1723
|
+
return {
|
|
1724
|
+
orderId: orderResult.orderId,
|
|
1725
|
+
orderNumber: orderResult.orderId,
|
|
1726
|
+
// Will be overwritten by actual order number if returned
|
|
1727
|
+
status: "pending",
|
|
1728
|
+
total: 0,
|
|
1729
|
+
// Actual total comes from server
|
|
1730
|
+
message: "Order created successfully (tracked)"
|
|
1731
|
+
};
|
|
1732
|
+
}
|
|
1733
|
+
} catch {
|
|
1734
|
+
}
|
|
1711
1735
|
const orderData = {
|
|
1712
1736
|
items: cart.items.map((item) => ({
|
|
1713
1737
|
productId: item.productId,
|
|
@@ -1726,6 +1750,97 @@ var OmniSyncClient = class {
|
|
|
1726
1750
|
}
|
|
1727
1751
|
return result;
|
|
1728
1752
|
}
|
|
1753
|
+
/**
|
|
1754
|
+
* Start a tracked guest checkout session (if enabled on connection)
|
|
1755
|
+
*
|
|
1756
|
+
* This creates Cart + Checkout records on the server so the store admin
|
|
1757
|
+
* can see checkout sessions and track abandoned carts.
|
|
1758
|
+
*
|
|
1759
|
+
* If tracking is not enabled for this connection, returns { tracked: false }.
|
|
1760
|
+
* If tracking is enabled, returns { tracked: true, checkoutId, cartId }.
|
|
1761
|
+
*
|
|
1762
|
+
* @example
|
|
1763
|
+
* ```typescript
|
|
1764
|
+
* // When customer goes to checkout page
|
|
1765
|
+
* const result = await omni.startGuestCheckout();
|
|
1766
|
+
*
|
|
1767
|
+
* if (result.tracked) {
|
|
1768
|
+
* // Store checkoutId for later use
|
|
1769
|
+
* console.log('Checkout tracked:', result.checkoutId);
|
|
1770
|
+
*
|
|
1771
|
+
* // Update checkout with address
|
|
1772
|
+
* await omni.updateGuestCheckout(result.checkoutId, {
|
|
1773
|
+
* shippingAddress: { ... },
|
|
1774
|
+
* });
|
|
1775
|
+
*
|
|
1776
|
+
* // Complete checkout
|
|
1777
|
+
* const order = await omni.completeGuestCheckout(result.checkoutId);
|
|
1778
|
+
* } else {
|
|
1779
|
+
* // Tracking not enabled, use regular submitGuestOrder
|
|
1780
|
+
* const order = await omni.submitGuestOrder();
|
|
1781
|
+
* }
|
|
1782
|
+
* ```
|
|
1783
|
+
*/
|
|
1784
|
+
async startGuestCheckout() {
|
|
1785
|
+
const cart = this.getLocalCart();
|
|
1786
|
+
if (cart.items.length === 0) {
|
|
1787
|
+
throw new OmniSyncError("Cart is empty", 400);
|
|
1788
|
+
}
|
|
1789
|
+
const response = await this.vibeCodedRequest(
|
|
1790
|
+
"POST",
|
|
1791
|
+
"/guest-checkout",
|
|
1792
|
+
{
|
|
1793
|
+
items: cart.items.map((item) => ({
|
|
1794
|
+
productId: item.productId,
|
|
1795
|
+
variantId: item.variantId,
|
|
1796
|
+
quantity: item.quantity
|
|
1797
|
+
})),
|
|
1798
|
+
customer: cart.customer
|
|
1799
|
+
}
|
|
1800
|
+
);
|
|
1801
|
+
return response;
|
|
1802
|
+
}
|
|
1803
|
+
/**
|
|
1804
|
+
* Update a tracked guest checkout with shipping/billing address
|
|
1805
|
+
* Use after startGuestCheckout() returns { tracked: true }
|
|
1806
|
+
*/
|
|
1807
|
+
async updateGuestCheckoutAddress(checkoutId, data) {
|
|
1808
|
+
let checkout = null;
|
|
1809
|
+
if (data.shippingAddress) {
|
|
1810
|
+
const result = await this.vibeCodedRequest(
|
|
1811
|
+
"PATCH",
|
|
1812
|
+
`/checkout/${checkoutId}/shipping-address`,
|
|
1813
|
+
data.shippingAddress
|
|
1814
|
+
);
|
|
1815
|
+
checkout = result.checkout;
|
|
1816
|
+
}
|
|
1817
|
+
if (data.billingAddress) {
|
|
1818
|
+
checkout = await this.vibeCodedRequest(
|
|
1819
|
+
"PATCH",
|
|
1820
|
+
`/checkout/${checkoutId}/billing-address`,
|
|
1821
|
+
data.billingAddress
|
|
1822
|
+
);
|
|
1823
|
+
}
|
|
1824
|
+
if (!checkout) {
|
|
1825
|
+
throw new OmniSyncError("No address data provided", 400);
|
|
1826
|
+
}
|
|
1827
|
+
return checkout;
|
|
1828
|
+
}
|
|
1829
|
+
/**
|
|
1830
|
+
* Complete a tracked guest checkout - creates the order
|
|
1831
|
+
* Use after startGuestCheckout() and updateGuestCheckoutAddress()
|
|
1832
|
+
*/
|
|
1833
|
+
async completeGuestCheckout(checkoutId, options) {
|
|
1834
|
+
const result = await this.vibeCodedRequest(
|
|
1835
|
+
"POST",
|
|
1836
|
+
`/checkout/${checkoutId}/complete`,
|
|
1837
|
+
{}
|
|
1838
|
+
);
|
|
1839
|
+
if (options?.clearCartOnSuccess !== false) {
|
|
1840
|
+
this.clearLocalCart();
|
|
1841
|
+
}
|
|
1842
|
+
return result;
|
|
1843
|
+
}
|
|
1729
1844
|
/**
|
|
1730
1845
|
* Create order from custom data (not from local cart)
|
|
1731
1846
|
* Use this if you manage cart state yourself
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "omni-sync-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.1",
|
|
4
4
|
"description": "Official SDK for building e-commerce storefronts with OmniSync Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"module": "dist/index.mjs",
|