Skip to main content

⚙️ Alphabite Medusa SDK

The Alphabite Medusa SDK is a drop-in replacement for the official @medusajs/js-sdk with built-in support for Alphabite plugins like Wishlists, Reviews, and PayPal.

This SDK simplifies client-side integration with your Medusa backend, and provides a unified interface for accessing plugin functionality alongside core Medusa features.

🔧 Why Use It?​

  • ✅ Plug-and-play Medusa SDK replacement
  • 🔌 Seamless plugin injection and namespaced usage
  • 🔐 Flexible auth handling with global or per-request headers
  • 🧩 Tight TypeScript support across all plugins
  • ⚙️ Customizable and easy to extend

📦 Installation​

npm install @alphabite/medusa-sdk

🚀 Basic Usage​

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

const sdk = new AlphabiteMedusaSdk(
  {
    baseUrl: "https://your-medusa-api.com/api",
    publishableKey: "pk_...",
  },
  [wishlistPlugin, paypalPlugin, reviewsPlugin],
  {
    getAuthHeader: async () => {
      const token = await getTokenFromStorage();
      return { authorization: `Bearer ${token}` };
    },
  }
);

🧩 Plugin Architecture​

All Alphabite plugins are injected via the second parameter when creating the SDK instance. They register under a namespaced sdk.alphabite object. For example:

sdk.alphabite.wishlist.create({ name: "My Wishlist" });
sdk.alphabite.reviews.list({ product_id: "prod_123" });

🔐 Auth Handling​

You can pass an optional getAuthHeader function to automatically attach authorization headers to every request.

const sdk = new AlphabiteMedusaSdk({ baseUrl }, [wishlistPlugin], {
  getAuthHeader: async () => {
    const token = await getAccessToken();
    return { authorization: `Bearer ${token}` };
  },
});

You can also pass headers per request:

await sdk.alphabite.wishlist.create({ name: "Private Wishlist" }, { "x-request-id": "my-id" });

✅ Example: Wishlist Flow​

await sdk.alphabite.wishlist.create({ name: "My Gear" });

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

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

📁 Recommended Structure​

Centralize your SDK instance:

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

export const sdk = new AlphabiteMedusaSdk(
  { baseUrl: process.env.NEXT_PUBLIC_API_URL! }, 
  [wishlistPlugin], 
  {
  getAuthHeader: async () => {
    const token = await getToken();
    return { authorization: `Bearer ${token}` };
  },
});

Then import sdk anywhere in your app:

import { sdk } from "@/lib/sdk";

const { data: lists } = await sdk.alphabite.wishlist.list();

📚 Supported Plugins​

PluginNamespaceDescription
Wishlistsdk.alphabite.wishlistCreate and manage wishlists
Reviewssdk.alphabite.reviewsCustomer product reviews
PayPalsdk.alphabite.paypalPayment integration

More plugins are coming soon.

🧪 TypeScript Support​

This SDK ships with full TypeScript types for all plugin methods and payloads. You get full autocomplete, request typing, and strict response validation out of the box.

🤝 Contributing​

We're building this SDK to be extensible. If you want to create your own plugin or improve the SDK core, contributions are welcome.

📝 License​

MIT © Alphabite