omni-sync-sdk 0.7.10 → 0.8.0

package/README.md

@@ -853,8 +853,15 @@ const auth = await omni.registerCustomer({
   lastName: 'Doe',
 });
 
-setCustomerToken(auth.token);
-console.log('Registered:', auth.customer.email);
+// Check if email verification is required
+if (auth.requiresVerification) {
+  localStorage.setItem('verificationToken', auth.token);
+  window.location.href = '/verify-email';
+} else {
+  setCustomerToken(auth.token);
+  // Redirect back to store, not /account
+  window.location.href = '/';
+}
 ```
 
 #### Login Customer
@@ -862,12 +869,20 @@ console.log('Registered:', auth.customer.email);
 ```typescript
 const auth = await omni.loginCustomer('customer@example.com', 'password123');
 setCustomerToken(auth.token);
+
+// Best practice: redirect back to previous page or home
+const returnUrl = localStorage.getItem('returnUrl') || '/';
+localStorage.removeItem('returnUrl');
+window.location.href = returnUrl;
 ```
 
+> **Best Practice:** Before showing login page, save the current URL with `localStorage.setItem('returnUrl', window.location.pathname)`. After login, redirect back to that URL. This is how Amazon, Shopify, and most e-commerce sites work.
+
 #### Logout Customer
 
 ```typescript
 setCustomerToken(null);
+window.location.href = '/'; // Return to store home
 ```
 
 #### Get Customer Profile
@@ -930,9 +945,9 @@ if (auth.requiresVerification) {
   // Redirect to verification page
   window.location.href = '/verify-email';
 } else {
-  // No verification needed - proceed normally
+  // No verification needed - redirect back to store
   setCustomerToken(auth.token);
-  window.location.href = '/account';
+  window.location.href = '/';
 }
 ```
 
@@ -951,7 +966,10 @@ if (result.verified) {
   // Email verified! Now set the token for normal use
   setCustomerToken(token);
   localStorage.removeItem('verificationToken');
-  window.location.href = '/account';
+  // Redirect back to store (or returnUrl if saved)
+  const returnUrl = localStorage.getItem('returnUrl') || '/';
+  localStorage.removeItem('returnUrl');
+  window.location.href = returnUrl;
 }
 ```
 
@@ -996,7 +1014,10 @@ export default function VerifyEmailPage() {
         toast.success('Email verified!');
         setCustomerToken(token);
         localStorage.removeItem('verificationToken');
-        window.location.href = '/account';
+        // Redirect back to store
+        const returnUrl = localStorage.getItem('returnUrl') || '/';
+        localStorage.removeItem('returnUrl');
+        window.location.href = returnUrl;
       }
     } catch (error) {
       toast.error(error instanceof Error ? error.message : 'Verification failed');
@@ -1055,6 +1076,335 @@ export default function VerifyEmailPage() {
 
 ---
 
+### Social Login (OAuth)
+
+Allow customers to sign in with Google, Facebook, or GitHub. The store owner configures which providers are available in their OmniSync admin panel.
+
+#### Check Available Providers
+
+```typescript
+// Returns only the providers the store owner has enabled
+const { providers } = await omni.getAvailableOAuthProviders();
+// providers = ['GOOGLE', 'FACEBOOK'] - varies by store configuration
+```
+
+#### OAuth Login Flow
+
+**Step 1: User clicks "Sign in with Google"**
+
+```typescript
+// Save cart ID before redirect (user will leave your site!)
+const cartId = localStorage.getItem('cartId');
+if (cartId) sessionStorage.setItem('pendingCartId', cartId);
+
+// Get authorization URL
+const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl('GOOGLE', {
+  redirectUrl: window.location.origin + '/auth/callback', // Where Google sends them back
+});
+
+// Save state for verification (CSRF protection)
+sessionStorage.setItem('oauthState', state);
+
+// Redirect to Google
+window.location.href = authorizationUrl;
+```
+
+**Step 2: Create callback page (`/auth/callback`)**
+
+```typescript
+// pages/auth/callback.tsx or app/auth/callback/page.tsx
+'use client';
+import { useEffect, useState } from 'react';
+import { useSearchParams } from 'next/navigation';
+import { omni, setCustomerToken } from '@/lib/omni-sync';
+
+export default function AuthCallback() {
+  const searchParams = useSearchParams();
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function handleCallback() {
+      const code = searchParams.get('code');
+      const state = searchParams.get('state');
+      const errorParam = searchParams.get('error');
+
+      // Check for OAuth errors (user cancelled, etc.)
+      if (errorParam) {
+        window.location.href = '/login?error=cancelled';
+        return;
+      }
+
+      if (!code || !state) {
+        setError('Missing OAuth parameters');
+        return;
+      }
+
+      // Verify state matches (CSRF protection)
+      const savedState = sessionStorage.getItem('oauthState');
+      if (state !== savedState) {
+        setError('Invalid state - please try again');
+        return;
+      }
+
+      try {
+        // Exchange code for customer token
+        const { customer, token, isNewCustomer } = await omni.handleOAuthCallback(
+          'GOOGLE',
+          code,
+          state
+        );
+
+        // Save the customer token
+        setCustomerToken(token);
+        sessionStorage.removeItem('oauthState');
+
+        // Link any pending cart to the now-logged-in customer
+        const pendingCartId = sessionStorage.getItem('pendingCartId');
+        if (pendingCartId) {
+          try {
+            await omni.linkCart(pendingCartId);
+          } catch {
+            // Cart may have expired - that's ok
+          }
+          sessionStorage.removeItem('pendingCartId');
+        }
+
+        // Redirect to return URL or home
+        const returnUrl = localStorage.getItem('returnUrl') || '/';
+        localStorage.removeItem('returnUrl');
+        window.location.href = returnUrl;
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Login failed');
+      }
+    }
+
+    handleCallback();
+  }, [searchParams]);
+
+  if (error) {
+    return (
+      <div className="max-w-md mx-auto mt-12 text-center">
+        <h1 className="text-xl font-bold text-red-600">Login Failed</h1>
+        <p className="mt-2 text-gray-600">{error}</p>
+        <a href="/login" className="mt-4 inline-block text-blue-600">
+          Try again
+        </a>
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-md mx-auto mt-12 text-center">
+      <div className="animate-spin h-8 w-8 border-4 border-blue-600 border-t-transparent rounded-full mx-auto"></div>
+      <p className="mt-4 text-gray-600">Completing login...</p>
+    </div>
+  );
+}
+```
+
+#### Login Page with Social Buttons
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { omni, setCustomerToken } from '@/lib/omni-sync';
+
+export default function LoginPage() {
+  const [providers, setProviders] = useState<string[]>([]);
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  // Load available OAuth providers
+  useEffect(() => {
+    omni.getAvailableOAuthProviders()
+      .then(({ providers }) => setProviders(providers))
+      .catch(() => {}); // OAuth not configured - that's ok
+  }, []);
+
+  // Social login handler
+  const handleSocialLogin = async (provider: string) => {
+    try {
+      // Save cart ID before redirect
+      const cartId = localStorage.getItem('cartId');
+      if (cartId) sessionStorage.setItem('pendingCartId', cartId);
+
+      const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl(
+        provider as 'GOOGLE' | 'FACEBOOK' | 'GITHUB',
+        { redirectUrl: window.location.origin + '/auth/callback' }
+      );
+
+      sessionStorage.setItem('oauthState', state);
+      window.location.href = authorizationUrl;
+    } catch (err) {
+      setError('Failed to start login');
+    }
+  };
+
+  // Regular email/password login
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+    try {
+      const auth = await omni.loginCustomer(email, password);
+      setCustomerToken(auth.token);
+      const returnUrl = localStorage.getItem('returnUrl') || '/';
+      localStorage.removeItem('returnUrl');
+      window.location.href = returnUrl;
+    } catch (err) {
+      setError('Invalid email or password');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="max-w-md mx-auto mt-12">
+      <h1 className="text-2xl font-bold mb-6">Login</h1>
+
+      {/* Social Login Buttons */}
+      {providers.length > 0 && (
+        <div className="space-y-3 mb-6">
+          {providers.includes('GOOGLE') && (
+            <button
+              onClick={() => handleSocialLogin('GOOGLE')}
+              className="w-full flex items-center justify-center gap-2 border py-3 rounded hover:bg-gray-50"
+            >
+              <GoogleIcon />
+              Continue with Google
+            </button>
+          )}
+          {providers.includes('FACEBOOK') && (
+            <button
+              onClick={() => handleSocialLogin('FACEBOOK')}
+              className="w-full flex items-center justify-center gap-2 bg-[#1877F2] text-white py-3 rounded"
+            >
+              <FacebookIcon />
+              Continue with Facebook
+            </button>
+          )}
+          {providers.includes('GITHUB') && (
+            <button
+              onClick={() => handleSocialLogin('GITHUB')}
+              className="w-full flex items-center justify-center gap-2 bg-[#24292F] text-white py-3 rounded"
+            >
+              <GithubIcon />
+              Continue with GitHub
+            </button>
+          )}
+          <div className="relative my-4">
+            <div className="absolute inset-0 flex items-center">
+              <div className="w-full border-t" />
+            </div>
+            <div className="relative flex justify-center text-sm">
+              <span className="px-2 bg-white text-gray-500">or</span>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Email/Password Form */}
+      {error && <div className="bg-red-100 text-red-600 p-3 rounded mb-4">{error}</div>}
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <input
+          type="email"
+          placeholder="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          required
+          className="w-full border p-2 rounded"
+        />
+        <input
+          type="password"
+          placeholder="Password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          required
+          className="w-full border p-2 rounded"
+        />
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full bg-black text-white py-3 rounded"
+        >
+          {loading ? 'Logging in...' : 'Login'}
+        </button>
+      </form>
+
+      <p className="mt-4 text-center">
+        Don't have an account? <a href="/register" className="text-blue-600">Register</a>
+      </p>
+    </div>
+  );
+}
+
+// Simple SVG icons (or use lucide-react)
+const GoogleIcon = () => (
+  <svg className="w-5 h-5" viewBox="0 0 24 24">
+    <path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/>
+    <path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/>
+    <path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/>
+    <path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/>
+  </svg>
+);
+
+const FacebookIcon = () => (
+  <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+    <path d="M24 12.073c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.99 4.388 10.954 10.125 11.854v-8.385H7.078v-3.47h3.047V9.43c0-3.007 1.792-4.669 4.533-4.669 1.312 0 2.686.235 2.686.235v2.953H15.83c-1.491 0-1.956.925-1.956 1.874v2.25h3.328l-.532 3.47h-2.796v8.385C19.612 23.027 24 18.062 24 12.073z"/>
+  </svg>
+);
+
+const GithubIcon = () => (
+  <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+    <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/>
+  </svg>
+);
+```
+
+#### Account Linking (Add Social Account to Existing User)
+
+Logged-in customers can link additional social accounts to their profile:
+
+```typescript
+// Get currently linked accounts
+const connections = await omni.getOAuthConnections();
+// [{ provider: 'GOOGLE', email: 'user@gmail.com', linkedAt: '...' }]
+
+// Link a new provider (redirects to OAuth flow)
+const { authorizationUrl } = await omni.linkOAuthProvider('GITHUB');
+window.location.href = authorizationUrl;
+
+// Unlink a provider
+await omni.unlinkOAuthProvider('GOOGLE');
+```
+
+#### Cart Linking After OAuth Login
+
+When a customer logs in via OAuth, their guest cart should be linked to their account:
+
+```typescript
+// omni.linkCart() associates a guest cart with the logged-in customer
+await omni.linkCart(cartId);
+```
+
+This is automatically handled in the callback example above.
+
+#### OAuth Method Reference
+
+| Method                                       | Description                                  |
+| -------------------------------------------- | -------------------------------------------- |
+| `getAvailableOAuthProviders()`               | Get list of enabled providers for this store |
+| `getOAuthAuthorizeUrl(provider, options?)`   | Get URL to redirect user to OAuth provider   |
+| `handleOAuthCallback(provider, code, state)` | Exchange OAuth code for customer token       |
+| `linkOAuthProvider(provider)`                | Link social account to current customer      |
+| `unlinkOAuthProvider(provider)`              | Remove linked social account                 |
+| `getOAuthConnections()`                      | Get list of linked social accounts           |
+| `linkCart(cartId)`                           | Link guest cart to logged-in customer        |
+
+---
+
 ### Customer Addresses
 
 #### Get Addresses
@@ -1767,7 +2117,7 @@ export default function CheckoutPage() {
 
 ```typescript
 'use client';
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
 import { omni, setCustomerToken } from '@/lib/omni-sync';
 
 export default function LoginPage() {
@@ -1776,6 +2126,15 @@ export default function LoginPage() {
   const [error, setError] = useState('');
   const [loading, setLoading] = useState(false);
 
+  // Save the page user came from (for redirect after login)
+  useEffect(() => {
+    const referrer = document.referrer;
+    if (referrer && !referrer.includes('/login') && !referrer.includes('/register')) {
+      const url = new URL(referrer);
+      localStorage.setItem('returnUrl', url.pathname);
+    }
+  }, []);
+
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
     setLoading(true);
@@ -1783,7 +2142,11 @@ export default function LoginPage() {
     try {
       const auth = await omni.loginCustomer(email, password);
       setCustomerToken(auth.token);
-      window.location.href = '/account';
+
+      // Redirect back to previous page or home (like Amazon/Shopify do)
+      const returnUrl = localStorage.getItem('returnUrl') || '/';
+      localStorage.removeItem('returnUrl');
+      window.location.href = returnUrl;
     } catch (err) {
       setError('Invalid email or password');
     } finally {
@@ -1814,7 +2177,7 @@ export default function LoginPage() {
 
 ```typescript
 'use client';
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
 import { omni, setCustomerToken } from '@/lib/omni-sync';
 
 export default function RegisterPage() {
@@ -1825,6 +2188,15 @@ export default function RegisterPage() {
   const [error, setError] = useState('');
   const [loading, setLoading] = useState(false);
 
+  // Save the page user came from (for redirect after registration)
+  useEffect(() => {
+    const referrer = document.referrer;
+    if (referrer && !referrer.includes('/login') && !referrer.includes('/register')) {
+      const url = new URL(referrer);
+      localStorage.setItem('returnUrl', url.pathname);
+    }
+  }, []);
+
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
     setLoading(true);
@@ -1838,9 +2210,11 @@ export default function RegisterPage() {
         localStorage.setItem('verificationToken', auth.token);
         window.location.href = '/verify-email';
       } else {
-        // No verification needed - proceed normally
+        // No verification needed - redirect back to store (like Amazon/Shopify)
         setCustomerToken(auth.token);
-        window.location.href = '/account';
+        const returnUrl = localStorage.getItem('returnUrl') || '/';
+        localStorage.removeItem('returnUrl');
+        window.location.href = returnUrl;
       }
     } catch (err) {
       setError('Registration failed. Email may already be in use.');
@@ -2143,8 +2517,9 @@ When building a store, implement these pages:
 - [ ] **Product Detail** (`/products/[id]`) - Single product with Add to Cart
 - [ ] **Cart** (`/cart`) - Cart items, update quantity, remove
 - [ ] **Checkout** (`/checkout`) - Multi-step checkout flow
-- [ ] **Login** (`/login`) - Customer login
-- [ ] **Register** (`/register`) - Customer registration
+- [ ] **Login** (`/login`) - Customer login + social login buttons (Google/Facebook/GitHub if available)
+- [ ] **Register** (`/register`) - Customer registration + social signup buttons
+- [ ] **Auth Callback** (`/auth/callback`) - Handle OAuth redirects from Google/Facebook/GitHub
 - [ ] **Verify Email** (`/verify-email`) - Email verification with 6-digit code (if store requires it)
 - [ ] **Account** (`/account`) - Profile and order history
 

package/dist/index.d.mts

@@ -505,6 +505,30 @@ interface EmailVerificationResponse {
     verified: boolean;
     message: string;
 }
+type CustomerOAuthProvider = 'GOOGLE' | 'FACEBOOK' | 'GITHUB';
+interface OAuthAuthorizeResponse {
+    authorizationUrl: string;
+    state: string;
+    provider: CustomerOAuthProvider;
+}
+interface OAuthCallbackResponse extends CustomerAuthResponse {
+    isNewCustomer: boolean;
+    linkedToExisting: boolean;
+    provider: CustomerOAuthProvider;
+    redirectUrl?: string;
+}
+interface OAuthConnection {
+    id: string;
+    provider: CustomerOAuthProvider;
+    email?: string;
+    createdAt: string;
+}
+interface OAuthProvidersResponse {
+    providers: CustomerOAuthProvider[];
+}
+interface OAuthConnectionsResponse {
+    connections: OAuthConnection[];
+}
 interface RegisterCustomerDto {
     email: string;
     password: string;
@@ -1709,6 +1733,118 @@ declare class OmniSyncClient {
     resendVerificationEmail(token?: string): Promise<{
         message: string;
     }>;
+    /**
+     * Get available OAuth providers for this store
+     * Works in vibe-coded and storefront modes
+     *
+     * @example
+     * ```typescript
+     * const { providers } = await omni.getAvailableOAuthProviders();
+     * // providers: ['GOOGLE', 'FACEBOOK']
+     * ```
+     */
+    getAvailableOAuthProviders(): Promise<OAuthProvidersResponse>;
+    /**
+     * Get OAuth authorization URL for a provider
+     * Redirects user to provider's login page
+     * Works in vibe-coded and storefront modes
+     *
+     * @param provider - OAuth provider ('GOOGLE', 'FACEBOOK', 'GITHUB')
+     * @param options - Optional configuration
+     * @param options.redirectUrl - URL to redirect to after OAuth completes
+     *
+     * @example
+     * ```typescript
+     * // Get authorization URL
+     * const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl('GOOGLE', {
+     *   redirectUrl: 'https://mysite.com/auth/callback'
+     * });
+     *
+     * // Redirect user to authorizationUrl
+     * window.location.href = authorizationUrl;
+     * ```
+     */
+    getOAuthAuthorizeUrl(provider: CustomerOAuthProvider, options?: {
+        redirectUrl?: string;
+    }): Promise<OAuthAuthorizeResponse>;
+    /**
+     * Handle OAuth callback - exchange code for customer token
+     * Call this after user is redirected back from OAuth provider
+     * Works in vibe-coded and storefront modes
+     *
+     * @param provider - OAuth provider ('GOOGLE', 'FACEBOOK', 'GITHUB')
+     * @param code - Authorization code from OAuth provider
+     * @param state - State parameter from OAuth callback
+     *
+     * @example
+     * ```typescript
+     * // After user is redirected back with code and state in URL
+     * const urlParams = new URLSearchParams(window.location.search);
+     * const code = urlParams.get('code');
+     * const state = urlParams.get('state');
+     *
+     * const auth = await omni.handleOAuthCallback('GOOGLE', code, state);
+     * omni.setCustomerToken(auth.token);
+     *
+     * if (auth.isNewCustomer) {
+     *   console.log('Welcome, new customer!');
+     * }
+     * ```
+     */
+    handleOAuthCallback(provider: CustomerOAuthProvider, code: string, state: string): Promise<OAuthCallbackResponse>;
+    /**
+     * Link OAuth provider to current logged-in customer
+     * Returns authorization URL - redirect user there
+     * Requires customer to be logged in (setCustomerToken called first)
+     *
+     * @param provider - OAuth provider to link ('GOOGLE', 'FACEBOOK', 'GITHUB')
+     * @param options - Optional configuration
+     * @param options.redirectUrl - URL to redirect to after linking
+     *
+     * @example
+     * ```typescript
+     * // Customer must be logged in first
+     * omni.setCustomerToken(auth.token);
+     *
+     * // Get authorization URL for linking
+     * const { authorizationUrl } = await omni.linkOAuthProvider('GITHUB', {
+     *   redirectUrl: '/settings'
+     * });
+     *
+     * // Redirect user to link their GitHub account
+     * window.location.href = authorizationUrl;
+     * ```
+     */
+    linkOAuthProvider(provider: CustomerOAuthProvider, options?: {
+        redirectUrl?: string;
+    }): Promise<OAuthAuthorizeResponse>;
+    /**
+     * Unlink OAuth provider from current customer account
+     * Requires customer to be logged in
+     *
+     * @param provider - OAuth provider to unlink ('GOOGLE', 'FACEBOOK', 'GITHUB')
+     *
+     * @example
+     * ```typescript
+     * omni.setCustomerToken(auth.token);
+     * await omni.unlinkOAuthProvider('FACEBOOK');
+     * ```
+     */
+    unlinkOAuthProvider(provider: CustomerOAuthProvider): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get OAuth connections for current customer
+     * Requires customer to be logged in
+     *
+     * @example
+     * ```typescript
+     * omni.setCustomerToken(auth.token);
+     * const { connections } = await omni.getOAuthConnections();
+     * // connections: [{ id: '...', provider: 'GOOGLE', email: 'user@gmail.com', createdAt: '...' }]
+     * ```
+     */
+    getOAuthConnections(): Promise<OAuthConnectionsResponse>;
     /**
      * Get the current logged-in customer's profile
      * Requires a customer token to be set via setCustomerToken()
@@ -1870,6 +2006,20 @@ declare class OmniSyncClient {
      * ```
      */
     removeCoupon(cartId: string): Promise<Cart>;
+    /**
+     * Link a cart to the currently logged-in customer
+     * Use this after customer logs in to associate their guest cart with their account
+     * Requires customer token to be set via setCustomerToken()
+     *
+     * @example
+     * ```typescript
+     * // After customer logs in
+     * omni.setCustomerToken(authResponse.token);
+     * const cart = await omni.linkCart('cart_123');
+     * // Cart is now linked to the customer
+     * ```
+     */
+    linkCart(cartId: string): Promise<Cart>;
     /**
      * Merge a guest cart into a customer's cart (after login)
      * The guest cart items are moved to the customer's cart
@@ -2395,4 +2545,4 @@ declare function isWebhookEventType(event: WebhookEvent, type: WebhookEventType)
  */
 declare function createWebhookHandler(handlers: Partial<Record<WebhookEventType, (event: WebhookEvent) => Promise<void>>>): (payload: unknown) => Promise<void>;
 
-export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type CategorySuggestion, 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 EmailVerificationResponse, 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 ProductSuggestion, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SearchSuggestions, 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 };
+export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type CategorySuggestion, 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 CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type EmailVerificationResponse, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InventoryInfo, type InventorySyncStatus, type LocalCart, type LocalCartItem, type MergeCartsDto, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProvidersResponse, 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 ProductSuggestion, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SearchSuggestions, 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

@@ -505,6 +505,30 @@ interface EmailVerificationResponse {
     verified: boolean;
     message: string;
 }
+type CustomerOAuthProvider = 'GOOGLE' | 'FACEBOOK' | 'GITHUB';
+interface OAuthAuthorizeResponse {
+    authorizationUrl: string;
+    state: string;
+    provider: CustomerOAuthProvider;
+}
+interface OAuthCallbackResponse extends CustomerAuthResponse {
+    isNewCustomer: boolean;
+    linkedToExisting: boolean;
+    provider: CustomerOAuthProvider;
+    redirectUrl?: string;
+}
+interface OAuthConnection {
+    id: string;
+    provider: CustomerOAuthProvider;
+    email?: string;
+    createdAt: string;
+}
+interface OAuthProvidersResponse {
+    providers: CustomerOAuthProvider[];
+}
+interface OAuthConnectionsResponse {
+    connections: OAuthConnection[];
+}
 interface RegisterCustomerDto {
     email: string;
     password: string;
@@ -1709,6 +1733,118 @@ declare class OmniSyncClient {
     resendVerificationEmail(token?: string): Promise<{
         message: string;
     }>;
+    /**
+     * Get available OAuth providers for this store
+     * Works in vibe-coded and storefront modes
+     *
+     * @example
+     * ```typescript
+     * const { providers } = await omni.getAvailableOAuthProviders();
+     * // providers: ['GOOGLE', 'FACEBOOK']
+     * ```
+     */
+    getAvailableOAuthProviders(): Promise<OAuthProvidersResponse>;
+    /**
+     * Get OAuth authorization URL for a provider
+     * Redirects user to provider's login page
+     * Works in vibe-coded and storefront modes
+     *
+     * @param provider - OAuth provider ('GOOGLE', 'FACEBOOK', 'GITHUB')
+     * @param options - Optional configuration
+     * @param options.redirectUrl - URL to redirect to after OAuth completes
+     *
+     * @example
+     * ```typescript
+     * // Get authorization URL
+     * const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl('GOOGLE', {
+     *   redirectUrl: 'https://mysite.com/auth/callback'
+     * });
+     *
+     * // Redirect user to authorizationUrl
+     * window.location.href = authorizationUrl;
+     * ```
+     */
+    getOAuthAuthorizeUrl(provider: CustomerOAuthProvider, options?: {
+        redirectUrl?: string;
+    }): Promise<OAuthAuthorizeResponse>;
+    /**
+     * Handle OAuth callback - exchange code for customer token
+     * Call this after user is redirected back from OAuth provider
+     * Works in vibe-coded and storefront modes
+     *
+     * @param provider - OAuth provider ('GOOGLE', 'FACEBOOK', 'GITHUB')
+     * @param code - Authorization code from OAuth provider
+     * @param state - State parameter from OAuth callback
+     *
+     * @example
+     * ```typescript
+     * // After user is redirected back with code and state in URL
+     * const urlParams = new URLSearchParams(window.location.search);
+     * const code = urlParams.get('code');
+     * const state = urlParams.get('state');
+     *
+     * const auth = await omni.handleOAuthCallback('GOOGLE', code, state);
+     * omni.setCustomerToken(auth.token);
+     *
+     * if (auth.isNewCustomer) {
+     *   console.log('Welcome, new customer!');
+     * }
+     * ```
+     */
+    handleOAuthCallback(provider: CustomerOAuthProvider, code: string, state: string): Promise<OAuthCallbackResponse>;
+    /**
+     * Link OAuth provider to current logged-in customer
+     * Returns authorization URL - redirect user there
+     * Requires customer to be logged in (setCustomerToken called first)
+     *
+     * @param provider - OAuth provider to link ('GOOGLE', 'FACEBOOK', 'GITHUB')
+     * @param options - Optional configuration
+     * @param options.redirectUrl - URL to redirect to after linking
+     *
+     * @example
+     * ```typescript
+     * // Customer must be logged in first
+     * omni.setCustomerToken(auth.token);
+     *
+     * // Get authorization URL for linking
+     * const { authorizationUrl } = await omni.linkOAuthProvider('GITHUB', {
+     *   redirectUrl: '/settings'
+     * });
+     *
+     * // Redirect user to link their GitHub account
+     * window.location.href = authorizationUrl;
+     * ```
+     */
+    linkOAuthProvider(provider: CustomerOAuthProvider, options?: {
+        redirectUrl?: string;
+    }): Promise<OAuthAuthorizeResponse>;
+    /**
+     * Unlink OAuth provider from current customer account
+     * Requires customer to be logged in
+     *
+     * @param provider - OAuth provider to unlink ('GOOGLE', 'FACEBOOK', 'GITHUB')
+     *
+     * @example
+     * ```typescript
+     * omni.setCustomerToken(auth.token);
+     * await omni.unlinkOAuthProvider('FACEBOOK');
+     * ```
+     */
+    unlinkOAuthProvider(provider: CustomerOAuthProvider): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get OAuth connections for current customer
+     * Requires customer to be logged in
+     *
+     * @example
+     * ```typescript
+     * omni.setCustomerToken(auth.token);
+     * const { connections } = await omni.getOAuthConnections();
+     * // connections: [{ id: '...', provider: 'GOOGLE', email: 'user@gmail.com', createdAt: '...' }]
+     * ```
+     */
+    getOAuthConnections(): Promise<OAuthConnectionsResponse>;
     /**
      * Get the current logged-in customer's profile
      * Requires a customer token to be set via setCustomerToken()
@@ -1870,6 +2006,20 @@ declare class OmniSyncClient {
      * ```
      */
     removeCoupon(cartId: string): Promise<Cart>;
+    /**
+     * Link a cart to the currently logged-in customer
+     * Use this after customer logs in to associate their guest cart with their account
+     * Requires customer token to be set via setCustomerToken()
+     *
+     * @example
+     * ```typescript
+     * // After customer logs in
+     * omni.setCustomerToken(authResponse.token);
+     * const cart = await omni.linkCart('cart_123');
+     * // Cart is now linked to the customer
+     * ```
+     */
+    linkCart(cartId: string): Promise<Cart>;
     /**
      * Merge a guest cart into a customer's cart (after login)
      * The guest cart items are moved to the customer's cart
@@ -2395,4 +2545,4 @@ declare function isWebhookEventType(event: WebhookEvent, type: WebhookEventType)
  */
 declare function createWebhookHandler(handlers: Partial<Record<WebhookEventType, (event: WebhookEvent) => Promise<void>>>): (payload: unknown) => Promise<void>;
 
-export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type CategorySuggestion, 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 EmailVerificationResponse, 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 ProductSuggestion, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SearchSuggestions, 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 };
+export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type CategorySuggestion, 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 CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type EmailVerificationResponse, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InventoryInfo, type InventorySyncStatus, type LocalCart, type LocalCartItem, type MergeCartsDto, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProvidersResponse, 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 ProductSuggestion, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SearchSuggestions, 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

@@ -1187,6 +1187,195 @@ var OmniSyncClient = class {
       }
     }
   }
+  // ===================================================
+  // Customer OAuth (Social Login)
+  // ===================================================
+  /**
+   * Get available OAuth providers for this store
+   * Works in vibe-coded and storefront modes
+   *
+   * @example
+   * ```typescript
+   * const { providers } = await omni.getAvailableOAuthProviders();
+   * // providers: ['GOOGLE', 'FACEBOOK']
+   * ```
+   */
+  async getAvailableOAuthProviders() {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", "/oauth/providers");
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest("GET", "/oauth/providers");
+    }
+    throw new OmniSyncError(
+      "getAvailableOAuthProviders requires vibe-coded or storefront mode",
+      400
+    );
+  }
+  /**
+   * Get OAuth authorization URL for a provider
+   * Redirects user to provider's login page
+   * Works in vibe-coded and storefront modes
+   *
+   * @param provider - OAuth provider ('GOOGLE', 'FACEBOOK', 'GITHUB')
+   * @param options - Optional configuration
+   * @param options.redirectUrl - URL to redirect to after OAuth completes
+   *
+   * @example
+   * ```typescript
+   * // Get authorization URL
+   * const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl('GOOGLE', {
+   *   redirectUrl: 'https://mysite.com/auth/callback'
+   * });
+   *
+   * // Redirect user to authorizationUrl
+   * window.location.href = authorizationUrl;
+   * ```
+   */
+  async getOAuthAuthorizeUrl(provider, options) {
+    const params = new URLSearchParams();
+    if (options?.redirectUrl) {
+      params.set("redirectUrl", options.redirectUrl);
+    }
+    const queryString = params.toString();
+    const endpoint = `/oauth/${provider}/authorize${queryString ? `?${queryString}` : ""}`;
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", endpoint);
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest("GET", endpoint);
+    }
+    throw new OmniSyncError("getOAuthAuthorizeUrl requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Handle OAuth callback - exchange code for customer token
+   * Call this after user is redirected back from OAuth provider
+   * Works in vibe-coded and storefront modes
+   *
+   * @param provider - OAuth provider ('GOOGLE', 'FACEBOOK', 'GITHUB')
+   * @param code - Authorization code from OAuth provider
+   * @param state - State parameter from OAuth callback
+   *
+   * @example
+   * ```typescript
+   * // After user is redirected back with code and state in URL
+   * const urlParams = new URLSearchParams(window.location.search);
+   * const code = urlParams.get('code');
+   * const state = urlParams.get('state');
+   *
+   * const auth = await omni.handleOAuthCallback('GOOGLE', code, state);
+   * omni.setCustomerToken(auth.token);
+   *
+   * if (auth.isNewCustomer) {
+   *   console.log('Welcome, new customer!');
+   * }
+   * ```
+   */
+  async handleOAuthCallback(provider, code, state) {
+    const params = new URLSearchParams({ code, state });
+    const endpoint = `/oauth/${provider}/callback?${params.toString()}`;
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", endpoint);
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest("GET", endpoint);
+    }
+    throw new OmniSyncError("handleOAuthCallback requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Link OAuth provider to current logged-in customer
+   * Returns authorization URL - redirect user there
+   * Requires customer to be logged in (setCustomerToken called first)
+   *
+   * @param provider - OAuth provider to link ('GOOGLE', 'FACEBOOK', 'GITHUB')
+   * @param options - Optional configuration
+   * @param options.redirectUrl - URL to redirect to after linking
+   *
+   * @example
+   * ```typescript
+   * // Customer must be logged in first
+   * omni.setCustomerToken(auth.token);
+   *
+   * // Get authorization URL for linking
+   * const { authorizationUrl } = await omni.linkOAuthProvider('GITHUB', {
+   *   redirectUrl: '/settings'
+   * });
+   *
+   * // Redirect user to link their GitHub account
+   * window.location.href = authorizationUrl;
+   * ```
+   */
+  async linkOAuthProvider(provider, options) {
+    if (!this.customerToken) {
+      throw new OmniSyncError("Customer token is required. Call setCustomerToken() first.", 401);
+    }
+    const params = new URLSearchParams();
+    if (options?.redirectUrl) {
+      params.set("redirectUrl", options.redirectUrl);
+    }
+    const queryString = params.toString();
+    const endpoint = `/oauth/${provider}/link${queryString ? `?${queryString}` : ""}`;
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", endpoint);
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest("POST", endpoint);
+    }
+    throw new OmniSyncError("linkOAuthProvider requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Unlink OAuth provider from current customer account
+   * Requires customer to be logged in
+   *
+   * @param provider - OAuth provider to unlink ('GOOGLE', 'FACEBOOK', 'GITHUB')
+   *
+   * @example
+   * ```typescript
+   * omni.setCustomerToken(auth.token);
+   * await omni.unlinkOAuthProvider('FACEBOOK');
+   * ```
+   */
+  async unlinkOAuthProvider(provider) {
+    if (!this.customerToken) {
+      throw new OmniSyncError("Customer token is required. Call setCustomerToken() first.", 401);
+    }
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("DELETE", `/oauth/${provider}/link`);
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest("DELETE", `/oauth/${provider}/link`);
+    }
+    throw new OmniSyncError("unlinkOAuthProvider requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Get OAuth connections for current customer
+   * Requires customer to be logged in
+   *
+   * @example
+   * ```typescript
+   * omni.setCustomerToken(auth.token);
+   * const { connections } = await omni.getOAuthConnections();
+   * // connections: [{ id: '...', provider: 'GOOGLE', email: 'user@gmail.com', createdAt: '...' }]
+   * ```
+   */
+  async getOAuthConnections() {
+    if (!this.customerToken) {
+      throw new OmniSyncError("Customer token is required. Call setCustomerToken() first.", 401);
+    }
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "GET",
+        "/customers/me/oauth-connections"
+      );
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest(
+        "GET",
+        "/customers/me/oauth-connections"
+      );
+    }
+    throw new OmniSyncError("getOAuthConnections requires vibe-coded or storefront mode", 400);
+  }
   /**
    * Get the current logged-in customer's profile
    * Requires a customer token to be set via setCustomerToken()
@@ -1452,6 +1641,34 @@ var OmniSyncClient = class {
     }
     return this.adminRequest("DELETE", `/api/v1/cart/${cartId}/coupon`);
   }
+  /**
+   * Link a cart to the currently logged-in customer
+   * Use this after customer logs in to associate their guest cart with their account
+   * Requires customer token to be set via setCustomerToken()
+   *
+   * @example
+   * ```typescript
+   * // After customer logs in
+   * omni.setCustomerToken(authResponse.token);
+   * const cart = await omni.linkCart('cart_123');
+   * // Cart is now linked to the customer
+   * ```
+   */
+  async linkCart(cartId) {
+    if (!this.customerToken) {
+      throw new OmniSyncError(
+        "Customer must be logged in to link cart. Call setCustomerToken() first.",
+        401
+      );
+    }
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", `/cart/${cartId}/link`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("POST", `/cart/${cartId}/link`);
+    }
+    throw new OmniSyncError("linkCart is only available in vibe-coded or storefront mode", 400);
+  }
   /**
    * Merge a guest cart into a customer's cart (after login)
    * The guest cart items are moved to the customer's cart

package/dist/index.mjs

@@ -1162,6 +1162,195 @@ var OmniSyncClient = class {
       }
     }
   }
+  // ===================================================
+  // Customer OAuth (Social Login)
+  // ===================================================
+  /**
+   * Get available OAuth providers for this store
+   * Works in vibe-coded and storefront modes
+   *
+   * @example
+   * ```typescript
+   * const { providers } = await omni.getAvailableOAuthProviders();
+   * // providers: ['GOOGLE', 'FACEBOOK']
+   * ```
+   */
+  async getAvailableOAuthProviders() {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", "/oauth/providers");
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest("GET", "/oauth/providers");
+    }
+    throw new OmniSyncError(
+      "getAvailableOAuthProviders requires vibe-coded or storefront mode",
+      400
+    );
+  }
+  /**
+   * Get OAuth authorization URL for a provider
+   * Redirects user to provider's login page
+   * Works in vibe-coded and storefront modes
+   *
+   * @param provider - OAuth provider ('GOOGLE', 'FACEBOOK', 'GITHUB')
+   * @param options - Optional configuration
+   * @param options.redirectUrl - URL to redirect to after OAuth completes
+   *
+   * @example
+   * ```typescript
+   * // Get authorization URL
+   * const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl('GOOGLE', {
+   *   redirectUrl: 'https://mysite.com/auth/callback'
+   * });
+   *
+   * // Redirect user to authorizationUrl
+   * window.location.href = authorizationUrl;
+   * ```
+   */
+  async getOAuthAuthorizeUrl(provider, options) {
+    const params = new URLSearchParams();
+    if (options?.redirectUrl) {
+      params.set("redirectUrl", options.redirectUrl);
+    }
+    const queryString = params.toString();
+    const endpoint = `/oauth/${provider}/authorize${queryString ? `?${queryString}` : ""}`;
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", endpoint);
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest("GET", endpoint);
+    }
+    throw new OmniSyncError("getOAuthAuthorizeUrl requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Handle OAuth callback - exchange code for customer token
+   * Call this after user is redirected back from OAuth provider
+   * Works in vibe-coded and storefront modes
+   *
+   * @param provider - OAuth provider ('GOOGLE', 'FACEBOOK', 'GITHUB')
+   * @param code - Authorization code from OAuth provider
+   * @param state - State parameter from OAuth callback
+   *
+   * @example
+   * ```typescript
+   * // After user is redirected back with code and state in URL
+   * const urlParams = new URLSearchParams(window.location.search);
+   * const code = urlParams.get('code');
+   * const state = urlParams.get('state');
+   *
+   * const auth = await omni.handleOAuthCallback('GOOGLE', code, state);
+   * omni.setCustomerToken(auth.token);
+   *
+   * if (auth.isNewCustomer) {
+   *   console.log('Welcome, new customer!');
+   * }
+   * ```
+   */
+  async handleOAuthCallback(provider, code, state) {
+    const params = new URLSearchParams({ code, state });
+    const endpoint = `/oauth/${provider}/callback?${params.toString()}`;
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", endpoint);
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest("GET", endpoint);
+    }
+    throw new OmniSyncError("handleOAuthCallback requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Link OAuth provider to current logged-in customer
+   * Returns authorization URL - redirect user there
+   * Requires customer to be logged in (setCustomerToken called first)
+   *
+   * @param provider - OAuth provider to link ('GOOGLE', 'FACEBOOK', 'GITHUB')
+   * @param options - Optional configuration
+   * @param options.redirectUrl - URL to redirect to after linking
+   *
+   * @example
+   * ```typescript
+   * // Customer must be logged in first
+   * omni.setCustomerToken(auth.token);
+   *
+   * // Get authorization URL for linking
+   * const { authorizationUrl } = await omni.linkOAuthProvider('GITHUB', {
+   *   redirectUrl: '/settings'
+   * });
+   *
+   * // Redirect user to link their GitHub account
+   * window.location.href = authorizationUrl;
+   * ```
+   */
+  async linkOAuthProvider(provider, options) {
+    if (!this.customerToken) {
+      throw new OmniSyncError("Customer token is required. Call setCustomerToken() first.", 401);
+    }
+    const params = new URLSearchParams();
+    if (options?.redirectUrl) {
+      params.set("redirectUrl", options.redirectUrl);
+    }
+    const queryString = params.toString();
+    const endpoint = `/oauth/${provider}/link${queryString ? `?${queryString}` : ""}`;
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", endpoint);
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest("POST", endpoint);
+    }
+    throw new OmniSyncError("linkOAuthProvider requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Unlink OAuth provider from current customer account
+   * Requires customer to be logged in
+   *
+   * @param provider - OAuth provider to unlink ('GOOGLE', 'FACEBOOK', 'GITHUB')
+   *
+   * @example
+   * ```typescript
+   * omni.setCustomerToken(auth.token);
+   * await omni.unlinkOAuthProvider('FACEBOOK');
+   * ```
+   */
+  async unlinkOAuthProvider(provider) {
+    if (!this.customerToken) {
+      throw new OmniSyncError("Customer token is required. Call setCustomerToken() first.", 401);
+    }
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("DELETE", `/oauth/${provider}/link`);
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest("DELETE", `/oauth/${provider}/link`);
+    }
+    throw new OmniSyncError("unlinkOAuthProvider requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Get OAuth connections for current customer
+   * Requires customer to be logged in
+   *
+   * @example
+   * ```typescript
+   * omni.setCustomerToken(auth.token);
+   * const { connections } = await omni.getOAuthConnections();
+   * // connections: [{ id: '...', provider: 'GOOGLE', email: 'user@gmail.com', createdAt: '...' }]
+   * ```
+   */
+  async getOAuthConnections() {
+    if (!this.customerToken) {
+      throw new OmniSyncError("Customer token is required. Call setCustomerToken() first.", 401);
+    }
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "GET",
+        "/customers/me/oauth-connections"
+      );
+    }
+    if (this.isStorefrontMode()) {
+      return this.storefrontRequest(
+        "GET",
+        "/customers/me/oauth-connections"
+      );
+    }
+    throw new OmniSyncError("getOAuthConnections requires vibe-coded or storefront mode", 400);
+  }
   /**
    * Get the current logged-in customer's profile
    * Requires a customer token to be set via setCustomerToken()
@@ -1427,6 +1616,34 @@ var OmniSyncClient = class {
     }
     return this.adminRequest("DELETE", `/api/v1/cart/${cartId}/coupon`);
   }
+  /**
+   * Link a cart to the currently logged-in customer
+   * Use this after customer logs in to associate their guest cart with their account
+   * Requires customer token to be set via setCustomerToken()
+   *
+   * @example
+   * ```typescript
+   * // After customer logs in
+   * omni.setCustomerToken(authResponse.token);
+   * const cart = await omni.linkCart('cart_123');
+   * // Cart is now linked to the customer
+   * ```
+   */
+  async linkCart(cartId) {
+    if (!this.customerToken) {
+      throw new OmniSyncError(
+        "Customer must be logged in to link cart. Call setCustomerToken() first.",
+        401
+      );
+    }
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", `/cart/${cartId}/link`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("POST", `/cart/${cartId}/link`);
+    }
+    throw new OmniSyncError("linkCart is only available in vibe-coded or storefront mode", 400);
+  }
   /**
    * Merge a guest cart into a customer's cart (after login)
    * The guest cart items are moved to the customer's cart

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-sync-sdk",
-  "version": "0.7.10",
+  "version": "0.8.0",
   "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.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",