@raba7ni/raba7ni 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,10 @@
 # @raba7ni/raba7ni
 
-Official TypeScript SDK for the Raba7ni Coffee Loyalty Platform Developer API.
+Official TypeScript SDK for the Raba7ni Loyalty Platform Developer API.
+
+[![npm version](https://badge.fury.io/js/%40raba7ni%2Fraba7ni.svg)](https://www.npmjs.com/package/@raba7ni/raba7ni)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
 
 ## Installation
 
@@ -14,42 +18,412 @@ npm install @raba7ni/raba7ni
 import { Raba7niSDK } from '@raba7ni/raba7ni';
 
 const sdk = new Raba7niSDK({
-  appId: 'app_abc123def456789...',
-  apiKey: 'dev_xyz789uvw456...',
-  baseUrl: 'https://your-domain.com' // optional, defaults to production
+  appId: 'app_your_app_id',
+  apiKey: 'dev_your_api_key'
+  // baseUrl defaults to 'https://api.raba7ni.com'
 });
 
+// Test connection
+const scopes = await sdk.testConnection();
+console.log('Connected! Scopes:', scopes.scopes);
+
 // Validate a member
 const result = await sdk.validateMember(5, '+1234567890');
-console.log(result.is_member); // true/false
+console.log('Is member:', result.is_member);
+```
+
+### Local Development
+
+For local testing, specify your development server:
+
+```typescript
+const sdk = new Raba7niSDK({
+  appId: 'app_your_app_id',
+  apiKey: 'dev_your_api_key',
+  baseUrl: 'http://localhost:8000' // Only for local testing
+});
+```
+
+## Configuration
+
+```typescript
+const sdk = new Raba7niSDK({
+  appId: 'app_...',       // Required: Application ID
+  apiKey: 'dev_...',      // Required: API Key
+  baseUrl: 'https://...',  // Optional: defaults to 'https://api.raba7ni.com'
+  locale: 'en',            // Optional: Locale (default: 'en')
+  timeout: 30000,          // Optional: Request timeout ms (default: 30000)
+  maxRetries: 3,           // Optional: Max retry attempts (default: 3)
+  retryDelay: 1000         // Optional: Initial retry delay ms (default: 1000)
+});
+```
+
+---
+
+## API Reference
+
+### Connection & Scopes
+
+#### `testConnection()`
+Test API connection and get available scopes.
+
+```typescript
+const result = await sdk.testConnection();
+// { scopes: ['members:read', 'members:write', ...], application: { id, name } }
+```
+
+#### `getWebhookEvents()`
+Get list of available webhook events.
+
+```typescript
+const events = await sdk.getWebhookEvents();
+```
+
+---
+
+### Member APIs
+
+#### `validateMember(cardId, phoneNumber, options?)`
+Check if a phone number is a registered member.
+
+```typescript
+const result = await sdk.validateMember(5, '+1234567890', {
+  include_member_data: true
+});
+
+if (result.is_member) {
+  console.log('Member:', result.member);
+}
+```
+
+#### `getMemberDetails(cardId, phoneNumber)`
+Get detailed member information.
+
+```typescript
+const details = await sdk.getMemberDetails(5, '+1234567890');
+console.log('Points:', details.card_relationship.points);
+```
+
+#### `requestMemberOTP(email, cardId)`
+Request OTP for new member registration.
+
+```typescript
+const otp = await sdk.requestMemberOTP('john@example.com', 5);
+
+if (otp.member_exists) {
+  console.log('Member already registered');
+} else {
+  console.log('OTP sent, expires at:', otp.expires_at);
+}
+```
+
+#### `findOrCreateMember(request)`
+Find existing member or create new one. Optionally create order and award points.
+
+```typescript
+// Basic usage - find or create member
+const result = await sdk.findOrCreateMember({
+  card_id: 5,
+  name: 'John Doe',
+  email: 'john@example.com',
+  phone_number: '+1234567890',
+  verification_code: '123456' // Required for NEW members only
+});
 
-// Find or create a member with points
-const member = await sdk.findOrCreateMember({
+// With order and points
+const result = await sdk.findOrCreateMember({
   card_id: 5,
   name: 'John Doe',
   email: 'john@example.com',
   phone_number: '+1234567890',
+  create_order: true,
   order: {
     award_points: true,
-    total_amount: 50.00
+    total_amount: 50.00,
+    items: [
+      { name: 'Coffee', amount: 15.00 },
+      { name: 'Sandwich', amount: 35.00 }
+    ]
   }
 });
+
+console.log('Is new member:', result.is_new);
+console.log('Points awarded:', result.transaction?.points);
+```
+
+---
+
+### Card APIs
+
+#### `listCards()`
+Get all loyalty cards accessible by your API key.
+
+```typescript
+const { cards, total } = await sdk.listCards();
+cards.forEach(card => console.log(card.name));
 ```
 
-## Features
+#### `getCardInfo(cardId)`
+Get details about a specific card.
+
+```typescript
+const card = await sdk.getCardInfo(5);
+console.log('Points per currency:', card.points_per_currency);
+```
+
+#### `listCardRewards(cardId)`
+Get available rewards for a card.
+
+```typescript
+const { rewards } = await sdk.listCardRewards(5);
+rewards.forEach(reward => {
+  console.log(`${reward.name}: ${reward.points} points`);
+});
+```
+
+---
+
+### Claim Request APIs
+
+#### `listClaimRequests(cardId, status?)`
+Get claim requests for a card.
+
+```typescript
+// All claims
+const { claim_requests } = await sdk.listClaimRequests(5);
+
+// Filtered by status
+const pending = await sdk.listClaimRequests(5, 'pending');
+```
+
+#### `requestClaimOTP(memberEmail, cardId, rewardId?)`
+Request OTP for claiming a reward.
+
+```typescript
+const otp = await sdk.requestClaimOTP('john@example.com', 5, 10);
+console.log('Claim OTP expires:', otp.expires_at);
+```
+
+#### `createClaimRequest(request)`
+Create a new reward claim request.
+
+```typescript
+const { claim_request } = await sdk.createClaimRequest({
+  member_email: 'john@example.com',
+  card_id: 5,
+  reward_id: 10,
+  verification_code: '123456',
+  member_note: 'Please deliver to office'
+});
+
+console.log('Claim ID:', claim_request.id);
+console.log('Status:', claim_request.status); // 'pending'
+```
+
+#### `getClaimRequest(requestId)`
+Get claim request details.
+
+```typescript
+const { claim_request } = await sdk.getClaimRequest(123);
+```
+
+#### `approveClaimRequest(requestId, staffNote?)`
+Approve a pending claim request.
+
+```typescript
+const { claim_request } = await sdk.approveClaimRequest(123, 'Approved!');
+```
+
+#### `rejectClaimRequest(requestId, staffNote?)`
+Reject a pending claim request.
+
+```typescript
+const { claim_request } = await sdk.rejectClaimRequest(123, 'Out of stock');
+```
+
+---
+
+### Referral APIs
+
+#### `getReferralStats(cardId)`
+Get referral statistics for a card.
+
+```typescript
+const stats = await sdk.getReferralStats(5);
+console.log('Total referrals:', stats.total_referrals);
+console.log('Successful:', stats.successful_referrals);
+```
+
+#### `listReferrers(cardId)`
+Get top referrers for a card.
+
+```typescript
+const { referrers } = await sdk.listReferrers(5);
+referrers.forEach(r => {
+  console.log(`${r.member_name}: ${r.referral_count} referrals`);
+});
+```
+
+#### `listReferrerReferrals(cardId, memberId)`
+Get all referrals made by a specific member.
+
+```typescript
+const { referrals } = await sdk.listReferrerReferrals(5, 100);
+```
+
+#### `validateReferralCode(referralCode, cardId)`
+Check if a referral code is valid.
+
+```typescript
+const result = await sdk.validateReferralCode('REF123ABC', 5);
+if (result.is_valid) {
+  console.log('Referred by:', result.referrer?.name);
+}
+```
+
+#### `applyReferral(referralCode, cardId, refereeEmail)`
+Apply a referral code to a new member.
+
+```typescript
+const { referral } = await sdk.applyReferral('REF123ABC', 5, 'newbie@example.com');
+```
+
+---
+
+## Webhook Handling
+
+### Verifying Webhooks
+
+```typescript
+import { WebhookHandler } from '@raba7ni/raba7ni';
+
+const handler = new WebhookHandler('your_webhook_secret');
+
+// Express example
+app.post('/webhooks', (req, res) => {
+  const signature = req.headers['x-webhook-signature'];
+  const payload = JSON.stringify(req.body);
+
+  handler.handleWebhook(payload, signature, {
+    onMemberJoined: async (data) => {
+      console.log('New member:', data.member.name);
+    },
+    onMemberLeft: async (data) => {
+      console.log('Member left:', data.member.name);
+    },
+    onClaimRequestCreated: async (data) => {
+      console.log('New claim:', data.claim_request.id);
+    },
+    onClaimRequestProcessed: async (data) => {
+      console.log('Claim processed:', data.status);
+    },
+    onUnknownEvent: async (event, data) => {
+      console.log('Unknown event:', event);
+    }
+  });
+
+  res.status(200).send('OK');
+});
+```
+
+### Manual Verification
+
+```typescript
+import { verifyWebhookSignature, parseWebhookPayload } from '@raba7ni/raba7ni';
+
+const isValid = verifyWebhookSignature(payload, signature, secret);
+if (isValid) {
+  const webhook = parseWebhookPayload(payload);
+  console.log('Event:', webhook.event);
+}
+```
+
+---
+
+## Error Handling
+
+```typescript
+import { 
+  Raba7niError, 
+  AuthenticationError, 
+  RateLimitError, 
+  ValidationError 
+} from '@raba7ni/raba7ni';
+
+try {
+  await sdk.validateMember(5, '+123');
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid credentials');
+  } else if (error instanceof RateLimitError) {
+    console.error('Rate limited, retry after:', error.retryAfter);
+  } else if (error instanceof ValidationError) {
+    console.error('Validation errors:', error.validationErrors);
+  } else if (error instanceof Raba7niError) {
+    console.error('API error:', error.message, error.code);
+  }
+}
+```
+
+---
+
+## Rate Limiting
+
+The SDK tracks rate limits automatically:
+
+```typescript
+const info = sdk.getRateLimitInfo();
+console.log('Hourly remaining:', info.hourlyRemaining);
+console.log('Daily remaining:', info.dailyRemaining);
+```
+
+---
+
+## Utilities
+
+```typescript
+import { 
+  normalizePhoneNumber, 
+  validateEmail, 
+  validateCardId 
+} from '@raba7ni/raba7ni';
+
+// Normalize phone numbers
+normalizePhoneNumber('+1 (555) 123-4567'); // '+15551234567'
+
+// Validate email format
+validateEmail('test@example.com'); // true
+
+// Validate card ID
+validateCardId('5'); // 5 (number)
+```
+
+---
+
+## TypeScript Types
+
+All types are exported for full TypeScript support:
+
+```typescript
+import type {
+  Member,
+  Card,
+  Reward,
+  ClaimRequest,
+  Order,
+  Transaction,
+  WebhookPayload,
+  ClaimRequestCreatedWebhookData,
+  ClaimRequestProcessedWebhookData
+} from '@raba7ni/raba7ni';
+```
 
-- ✅ Full TypeScript support with comprehensive types
-- ✅ Automatic authentication handling
-- ✅ Rate limiting with automatic retry logic
-- ✅ Comprehensive error handling
-- ✅ Input validation
-- ✅ Webhook signature verification utilities
-- ✅ Node.js 18+ support
-- ✅ ES modules and CommonJS compatibility
+---
 
-## Documentation
+## Requirements
 
-For complete API documentation, see the [Developer API Documentation](https://docs.raba7ni.com/developer-api).
+- Node.js 18+
+- TypeScript 5.0+ (for TypeScript users)
 
 ## License