⚙️ Alphabite Medusa Sdk

Drop-in replacement for @medusajs/js-sdk with plugin support for Wishlists, PayPal, Reviews, and more.

The Alphabite Medusa Sdk wraps the Medusa JS SDK and adds support for rich frontend integrations via plugin architecture.

📚 Table of Contents

• 📦 Installation
• 🚀 Usage
• 🔁 Drop-in Replacement
• 🔌 Plugin Injection
• 🔐 Auth Handling
• ✅ Example: Wishlist Usage
• 🧩 Plugins Included
• 🧪 TypeScript Support
• 📁 Folder Structure Tip
• 🤝 Contributing
• 📝 License

📦 Installation

npm install @alphabite/medusa-sdk

🚀 Usage

import {
  AlphabiteMedusaSdk,
  wishlistPlugin,
  paypalPlugin,
  reviewsPlugin,
} from '@alphabite/medusa-sdk'

const sdk = new AlphabiteMedusaSdk(
  {
    baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000/api',
    debug: process.env.NODE_ENV === 'development',
    publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
  },
  [wishlistPlugin, paypalPlugin, reviewsPlugin],

  // Optional options config to add a global getAuthHeader function for all endpoints
  {
    // supports async functions, for example a server action that fetches the token from headers
    getAuthHeader: async () => {
      const token = await getToken(); // your own function that returns the auth token

      return {
        authorization: `Bearer ${token}`,
      }
    },
  }
)

🔁 Drop-in Replacement

To migrate from the default Medusa SDK:

// BEFORE
import Medusa from '@medusajs/js-sdk'
const sdk = new Medusa({
  baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000/api',
  debug: process.env.NODE_ENV === 'development',
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
})

// AFTER
import { AlphabiteMedusaSdk, wishlistPlugin } from '@alphabite/medusa-sdk'

const sdk = new AlphabiteMedusaSdk({
    baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000/api',
    debug: process.env.NODE_ENV === 'development',
    publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
  },
  [wishlistPlugin], {
    // supports async functions, for example a server action that fetches the token from headers
    getAuthHeader: async () => {
      const token = await getToken(); // your own function that returns the auth token

      return {
        authorization: `Bearer ${token}`,
      }
    },
  }
)

🔌 Plugin Injection

Pass an array of plugins as the second argument:

[wishlistPlugin]

Each plugin registers a namespace like:

sdk.alphabite.wishlist

🔐 Auth Handling

1. Global headers with getAuthHeader

const sdk = new AlphabiteMedusaSdk(
  { baseUrl },
  [wishlistPlugin],
  {
    // supports async function, for example a server action that fetches the token from headers
    getAuthHeader: async () => {
      const token = await getToken(); // your own function that returns the auth token

      return {
        authorization: `Bearer ${token}`,
      }
    },
  }
)

2. Per-request headers

await sdk.alphabite.wishlist.create({ name: 'Favorites' }, {
  'x-request-id': 'abc',
})

✅ Example: Wishlist Usage

await sdk.alphabite.wishlist.create({ name: 'My Sneakers' })

await sdk.alphabite.wishlist.addItem({
  id: 'wishlist_id',
  product_id: 'variant_id',
})

const { data: items } = await sdk.alphabite.wishlist.listItems({
  id: 'wishlist_id',
})

🧩 Plugins Included

| Plugin | Namespace | Description | |---------------|-------------------|-------------------------------------| | wishlist | sdk.alphabite.wishlist | Multi-wishlist system | | reviews | sdk.alphabite.reviews | Reviews | | paypal | sdk.alphabite.paypal | Paypal |

🧪 TypeScript Support

Includes full types for every plugin endpoint:

• Wishlist, WishlistItem, AddItemToWishlistInput, etc.
• Fully typed SDK, request bodies, and responses

📁 Folder Structure Tip

Create a central instance:

// lib/sdk.ts
import {
  AlphabiteMedusaSdk,
  wishlistPlugin,
} from '@alphabite/medusa-sdk'

export const sdk = new AlphabiteMedusaSdk(
  { baseUrl: process.env.NEXT_PUBLIC_API_URL! },
  [wishlistPlugin],
  {
    // supports async function, for example a server action that fetches the token from headers
    getAuthHeader: async () => {
      const token = await getToken(); // your own function that returns the auth token

      return {
        authorization: `Bearer ${token}`,
      }
    },
  }
)

Use across your app:

import { sdk } from '@/lib/sdk'

await sdk.alphabite.wishlist.list({ limit: 10 })

🤝 Contributing

Want to build plugins or extend core support? PRs are welcome!

📝 License

MIT © Alphabite — extend and use freely.