@shopplus/membership-sdk

Membership platform Data SDK for ShopPlus / Shopify / ShopLine stores. Zero runtime dependencies, gzip < 5KB.

Features

• Token exchange, auto-refresh, and session management
• Email/password, SMS, OAuth, and platform token login
• Member profile, level, and points queries
• Loyalty discount calculation
• Points exchange store
• Referral / invite system
• Full TypeScript types with L1 anti-corruption layer (camelCase models)
• Event bus for reactive state updates
• i18n-ready error codes (106 error codes mapped to message keys)

Install

npm install @shopplus/membership-sdk

Quick Start

import { MembershipClient } from '@shopplus/membership-sdk';

const client = new MembershipClient({
  baseUrl: 'https://api.membership.example.com',
  tenantId: 'your_tenant_id',
});

// Auth: exchange platform token
await client.exchangeToken(platformToken, 'shopplus');

// Or: email login
const result = await client.auth.login({ email: '[email protected]', password: '...' });
// result.token.accessToken, result.user.userMemberId

// Query member profile
const user = await client.member.getProfile();
console.log(user.nickname, user.activePoints, user.currentLevel);

// Query points balance
const balance = await client.points.getBalance();
console.log(balance.available, balance.pending);

Authentication

Four login methods are supported:

// 1. Email + password
await client.auth.login({ email, password });

// 2. SMS verification code
await client.auth.sendSmsCode({ phone: '1234567890', countryCode: '+1' });
await client.auth.smsLogin({ phone: '1234567890', countryCode: '+1', code: '123456' });

// 3. OAuth (Google / Facebook / Apple / Line)
const url = await client.auth.getOAuthUrl('google');
// redirect user to url, then handle callback:
await client.auth.handleOAuthCallback('google', { code, state });

// 4. Platform token exchange
await client.exchangeToken(platformToken, 'shopify');

Token auto-refresh is built-in. Subscribe to token changes:

client.events.on('token-refreshed', (token) => {
  // persist token externally
});

API Modules

All modules are accessible via the client instance:

| Module | Methods | |---|---| | client.member | getProfile(), getLevel() | | client.points | getBalance(), getTransactions() | | client.loyalty | calculateDiscount() | | client.exchange | getProducts(), redeem() | | client.referral | getStats(), getLink(), getInvitees(), bindReferrer() | | client.auth | login(), register(), verifyEmail(), smsLogin(), getOAuthUrl(), ... |

Error Handling

import { MembershipError, SDKErrorCode } from '@shopplus/membership-sdk';

try {
  await client.points.getBalance();
} catch (err) {
  if (err instanceof MembershipError) {
    err.code;          // Business code (210xxx/211xxx) or SDK code (1xxx)
    err.messageKey;    // i18n key, e.g. 'sdk.error.210956'
    err.httpStatus;    // HTTP status
    err.serverMessage; // Raw server message (fallback)

    if (err.isNetworkError) { /* timeout, offline, etc. */ }
    if (err.isBusinessError) { /* server-side business error */ }
  }
}

Configuration

interface MembershipClientConfig {
  baseUrl: string;           // API base URL
  tenantId: string;          // Tenant identifier
  language?: string;         // Preferred locale (default: navigator.language)
  timeout?: number;          // Request timeout in ms (default: 10000)
  tokenProvider?: () => string | null;  // External token provider
}

Module Formats

| Format | File | Usage | |---|---|---| | ESM | dist/index.es.js | import in bundlers | | UMD | dist/index.umd.js | <script> tag or RequireJS | | Types | dist/index.d.ts | TypeScript support |

Browser Support

ES2017+ (Chrome 61+, Firefox 60+, Safari 11+, Edge 79+)

License

MIT