@raba7ni/raba7ni 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# @raba7ni/raba7ni
+
+Official TypeScript SDK for the Raba7ni Coffee Loyalty Platform Developer API.
+
+## Installation
+
+```bash
+npm install @raba7ni/raba7ni
+```
+
+## Quick Start
+
+```typescript
+import { Raba7niSDK } from '@raba7ni/raba7ni';
+
+const sdk = new Raba7niSDK({
+  appId: 'app_abc123def456789...',
+  apiKey: 'dev_xyz789uvw456...',
+  baseUrl: 'https://your-domain.com' // optional, defaults to production
+});
+
+// Validate a member
+const result = await sdk.validateMember(5, '+1234567890');
+console.log(result.is_member); // true/false
+
+// Find or create a member with points
+const member = await sdk.findOrCreateMember({
+  card_id: 5,
+  name: 'John Doe',
+  email: 'john@example.com',
+  phone_number: '+1234567890',
+  order: {
+    award_points: true,
+    total_amount: 50.00
+  }
+});
+```
+
+## Features
+
+- ✅ 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
+
+For complete API documentation, see the [Developer API Documentation](https://docs.raba7ni.com/developer-api).
+
+## License
+
+MIT © Raba7ni

package/dist/client.d.ts

@@ -0,0 +1,56 @@
+import { AxiosRequestConfig } from 'axios';
+import { Raba7niConfig, ApiResponse, RateLimitInfo } from './types';
+/**
+ * Core API client for Raba7ni Developer API
+ */
+export declare class Raba7niClient {
+    private axiosInstance;
+    private config;
+    private rateLimitInfo;
+    constructor(config: Raba7niConfig);
+    /**
+     * Extract rate limit information from response headers
+     */
+    private extractRateLimitInfo;
+    /**
+     * Handle API errors and convert to appropriate error classes
+     */
+    private handleApiError;
+    /**
+     * Make HTTP request with retry logic
+     */
+    private request;
+    /**
+     * Sleep helper for retry delays
+     */
+    private sleep;
+    /**
+     * Get current rate limit information
+     */
+    getRateLimitInfo(): RateLimitInfo;
+    /**
+     * Make GET request
+     */
+    get<T = any>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * Make POST request
+     */
+    post<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * Make PUT request
+     */
+    put<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * Make PATCH request
+     */
+    patch<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * Make DELETE request
+     */
+    delete<T = any>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<Raba7niConfig>): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAc,EAAiB,kBAAkB,EAA6B,MAAM,OAAO,CAAC;AAC5F,OAAO,EACL,aAAa,EACb,WAAW,EAEX,aAAa,EAMd,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,aAAa,CAKnB;gBAEU,MAAM,EAAE,aAAa;IAiEjC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;OAEG;IACH,OAAO,CAAC,cAAc;IA0DtB;;OAEG;YACW,OAAO;IAkDrB;;OAEG;IACH,OAAO,CAAC,KAAK;IAeb;;OAEG;IACI,gBAAgB,IAAI,aAAa;IAIxC;;OAEG;IACU,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI5F;;OAEG;IACU,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAIzG;;OAEG;IACU,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAIxG;;OAEG;IACU,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI1G;;OAEG;IACU,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI/F;;OAEG;IACI,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;CAgB1D"}

package/dist/index.d.ts

@@ -0,0 +1,497 @@
+import { AxiosRequestConfig } from 'axios';
+
+/**
+ * Configuration options for the Raba7ni SDK
+ */
+interface Raba7niConfig {
+    /** Application ID (starts with 'app_') */
+    appId: string;
+    /** API key (starts with 'dev_') */
+    apiKey: string;
+    /** Base URL for API requests */
+    baseUrl?: string;
+    /** Locale for API requests (default: 'en') */
+    locale?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial retry delay in milliseconds (default: 1000) */
+    retryDelay?: number;
+}
+/**
+ * Standard API response wrapper
+ */
+interface ApiResponse<T = any> {
+    success: boolean;
+    data?: T;
+    message?: string;
+}
+/**
+ * API error response structure
+ */
+interface ApiError {
+    error: string;
+    message: string;
+    errors?: Record<string, string[]>;
+}
+/**
+ * Rate limit information from response headers
+ */
+interface RateLimitInfo {
+    hourlyLimit: number;
+    hourlyRemaining: number;
+    dailyLimit: number;
+    dailyRemaining: number;
+    resetTime?: string;
+}
+/**
+ * Member validation request
+ */
+interface ValidateMemberRequest {
+    card_id: number;
+    phone_number: string;
+    include_member_data?: boolean;
+}
+/**
+ * Member validation response
+ */
+interface ValidateMemberResponse {
+    card_id: number;
+    phone_number: string;
+    is_member: boolean;
+    validated_at: string;
+    member?: Member;
+}
+/**
+ * Member details request
+ */
+interface MemberDetailsRequest {
+    card_id: number;
+    phone_number: string;
+}
+/**
+ * Member details response
+ */
+interface MemberDetailsResponse {
+    member: Member;
+    card_relationship: CardRelationship;
+}
+/**
+ * Find or create member request
+ */
+interface FindOrCreateMemberRequest {
+    card_id: number;
+    name: string;
+    email: string;
+    phone_number: string;
+    create_order?: boolean;
+    order?: Order;
+}
+/**
+ * Order information for find/create member
+ */
+interface Order {
+    award_points?: boolean;
+    total_amount: number;
+    delivery_cost?: number;
+    items?: OrderItem[];
+}
+/**
+ * Order item
+ */
+interface OrderItem {
+    name: string;
+    amount: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Find or create member response
+ */
+interface FindOrCreateMemberResponse {
+    member: Member;
+    is_new: boolean;
+    matched_by: 'email' | 'phone' | null;
+    card_id: number;
+    order?: OrderResponse;
+    transaction?: Transaction;
+}
+/**
+ * Order response
+ */
+interface OrderResponse {
+    id: number;
+    total_amount: string;
+    delivery_cost?: string;
+    items?: OrderItem[];
+    points_awarded: boolean;
+    status: string;
+    created_at: string;
+}
+/**
+ * Card information
+ */
+interface Card {
+    id: number;
+    name: string;
+    description?: string;
+    club_id: number;
+    club_name: string;
+    reward_type: 'points' | 'stamps';
+    is_active: boolean;
+    created_at: string;
+}
+/**
+ * Member information
+ */
+interface Member {
+    id: number;
+    first_name?: string;
+    last_name?: string;
+    name?: string;
+    email?: string;
+    phone?: string;
+    created_at: string;
+}
+/**
+ * Card relationship information
+ */
+interface CardRelationship {
+    card_id: number;
+    points: number;
+    stamps: number;
+    joined_at: string;
+    last_updated: string;
+}
+/**
+ * Transaction information
+ */
+interface Transaction {
+    id: number;
+    points?: number;
+    stamps?: number;
+    event: string;
+    created_at: string;
+}
+/**
+ * Available API scope
+ */
+interface Scope {
+    id: string;
+    name: string;
+    description: string;
+}
+/**
+ * Available webhook event
+ */
+interface WebhookEvent {
+    id: string;
+    name: string;
+    description: string;
+    data_structure: string;
+}
+/**
+ * Webhook payload structure
+ */
+interface WebhookPayload<T = any> {
+    event: string;
+    application_id: number;
+    timestamp: string;
+    data: T;
+}
+/**
+ * Member joined webhook data
+ */
+interface MemberJoinedWebhookData {
+    member: Member;
+    card: Card;
+}
+/**
+ * Member left webhook data
+ */
+interface MemberLeftWebhookData {
+    member: Member;
+    card: Card;
+}
+/**
+ * Points earned webhook data
+ */
+interface PointsEarnedWebhookData {
+    member: Member;
+    card: Card;
+    transaction: Transaction;
+}
+/**
+ * Points redeemed webhook data
+ */
+interface PointsRedeemedWebhookData {
+    member: Member;
+    card: Card;
+    transaction: Transaction;
+}
+/**
+ * Transaction created webhook data
+ */
+interface TransactionCreatedWebhookData {
+    transaction: Transaction;
+    member: Member;
+    card: Card;
+}
+/**
+ * SDK initialization error
+ */
+declare class Raba7niError extends Error {
+    code?: string | undefined;
+    statusCode?: number | undefined;
+    response?: any | undefined;
+    constructor(message: string, code?: string | undefined, statusCode?: number | undefined, response?: any | undefined);
+}
+/**
+ * Authentication error
+ */
+declare class AuthenticationError extends Raba7niError {
+    constructor(message?: string);
+}
+/**
+ * Rate limit error
+ */
+declare class RateLimitError extends Raba7niError {
+    retryAfter?: number | undefined;
+    constructor(message?: string, retryAfter?: number | undefined);
+}
+/**
+ * Validation error
+ */
+declare class ValidationError extends Raba7niError {
+    validationErrors?: Record<string, string[]> | undefined;
+    constructor(message: string, validationErrors?: Record<string, string[]> | undefined);
+}
+/**
+ * Network error
+ */
+declare class NetworkError extends Raba7niError {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+
+/**
+ * Main Raba7ni SDK class
+ */
+declare class Raba7niSDK {
+    private client;
+    constructor(config: Raba7niConfig);
+    /**
+     * Validate if a phone number is a member of a specific card
+     */
+    validateMember(cardId: number | string, phoneNumber: string, options?: {
+        include_member_data?: boolean;
+    }): Promise<ValidateMemberResponse>;
+    /**
+     * Get detailed information about a member for a specific card
+     */
+    getMemberDetails(cardId: number | string, phoneNumber: string): Promise<MemberDetailsResponse>;
+    /**
+     * Find an existing member by email/phone, or create a new account.
+     * Optionally create an online order and/or award points.
+     */
+    findOrCreateMember(request: FindOrCreateMemberRequest): Promise<FindOrCreateMemberResponse>;
+    /**
+     * Get card information
+     */
+    getCardInfo(cardId: number | string): Promise<Card>;
+    /**
+     * Get available API scopes
+     */
+    getScopes(): Promise<Scope[]>;
+    /**
+     * Get available webhook events
+     */
+    getWebhookEvents(): Promise<WebhookEvent[]>;
+    /**
+     * Get current rate limit information
+     */
+    getRateLimitInfo(): RateLimitInfo;
+    /**
+     * Update SDK configuration
+     */
+    updateConfig(config: Partial<Raba7niConfig>): void;
+    /**
+     * Helper method to make custom API requests
+     */
+    request<T = any>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', endpoint: string, data?: any, options?: any): Promise<T>;
+}
+
+/**
+ * Core API client for Raba7ni Developer API
+ */
+declare class Raba7niClient {
+    private axiosInstance;
+    private config;
+    private rateLimitInfo;
+    constructor(config: Raba7niConfig);
+    /**
+     * Extract rate limit information from response headers
+     */
+    private extractRateLimitInfo;
+    /**
+     * Handle API errors and convert to appropriate error classes
+     */
+    private handleApiError;
+    /**
+     * Make HTTP request with retry logic
+     */
+    private request;
+    /**
+     * Sleep helper for retry delays
+     */
+    private sleep;
+    /**
+     * Get current rate limit information
+     */
+    getRateLimitInfo(): RateLimitInfo;
+    /**
+     * Make GET request
+     */
+    get<T = any>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * Make POST request
+     */
+    post<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * Make PUT request
+     */
+    put<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * Make PATCH request
+     */
+    patch<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * Make DELETE request
+     */
+    delete<T = any>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<Raba7niConfig>): void;
+}
+
+/**
+ * Webhook signature verification utilities
+ */
+/**
+ * Verify webhook signature
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
+/**
+ * Parse webhook payload with type safety
+ */
+declare function parseWebhookPayload<T = any>(payload: string): WebhookPayload<T>;
+/**
+ * Type guard for member joined webhook
+ */
+declare function isMemberJoinedWebhook(payload: WebhookPayload): payload is WebhookPayload<MemberJoinedWebhookData>;
+/**
+ * Type guard for member left webhook
+ */
+declare function isMemberLeftWebhook(payload: WebhookPayload): payload is WebhookPayload<MemberLeftWebhookData>;
+/**
+ * Type guard for points earned webhook
+ */
+declare function isPointsEarnedWebhook(payload: WebhookPayload): payload is WebhookPayload<PointsEarnedWebhookData>;
+/**
+ * Type guard for points redeemed webhook
+ */
+declare function isPointsRedeemedWebhook(payload: WebhookPayload): payload is WebhookPayload<PointsRedeemedWebhookData>;
+/**
+ * Type guard for transaction created webhook
+ */
+declare function isTransactionCreatedWebhook(payload: WebhookPayload): payload is WebhookPayload<TransactionCreatedWebhookData>;
+/**
+ * Webhook handler class
+ */
+declare class WebhookHandler {
+    private secret;
+    constructor(secret: string);
+    /**
+     * Verify and parse incoming webhook
+     */
+    verifyAndParse<T = any>(payload: string, signature: string): Promise<WebhookPayload<T>>;
+    /**
+     * Verify webhook signature
+     */
+    verifyWebhookSignature(payload: string, signature: string): boolean;
+    /**
+     * Parse webhook payload
+     */
+    parseWebhookPayload<T = any>(payload: string): WebhookPayload<T>;
+    /**
+     * Handle webhook with event-specific callbacks
+     */
+    handleWebhook(payload: string, signature: string, handlers: {
+        onMemberJoined?: (data: MemberJoinedWebhookData) => Promise<void> | void;
+        onMemberLeft?: (data: MemberLeftWebhookData) => Promise<void> | void;
+        onPointsEarned?: (data: PointsEarnedWebhookData) => Promise<void> | void;
+        onPointsRedeemed?: (data: PointsRedeemedWebhookData) => Promise<void> | void;
+        onTransactionCreated?: (data: TransactionCreatedWebhookData) => Promise<void> | void;
+        onUnknownEvent?: (event: string, data: any) => Promise<void> | void;
+    }): Promise<void>;
+    /**
+     * Update webhook secret
+     */
+    updateSecret(secret: string): void;
+    /**
+     * Get current secret
+     */
+    getSecret(): string;
+}
+
+/**
+ * Utility functions for the Raba7ni SDK
+ */
+/**
+ * Normalize phone number to E.164 format
+ */
+declare function normalizePhoneNumber(phoneNumber: string): string;
+/**
+ * Validate email format
+ */
+declare function validateEmail(email: string): boolean;
+/**
+ * Validate card ID
+ */
+declare function validateCardId(cardId: number | string): number;
+/**
+ * Validate monetary amount
+ */
+declare function validateAmount(amount: number | string): number;
+/**
+ * Sanitize string input
+ */
+declare function sanitizeString(input: string, maxLength?: number): string;
+/**
+ * Validate name field
+ */
+declare function validateName(name: string): string;
+/**
+ * Deep clone object
+ */
+declare function deepClone<T>(obj: T): T;
+/**
+ * Retry delay calculation with exponential backoff
+ */
+declare function calculateRetryDelay(attempt: number, baseDelay?: number): number;
+/**
+ * Generate random string for request tracking
+ */
+declare function generateRequestId(): string;
+/**
+ * Check if a value is a valid ISO date string
+ */
+declare function isValidISODate(dateString: string): boolean;
+/**
+ * Format date to ISO string
+ */
+declare function formatDate(date: Date | string): string;
+
+export { AuthenticationError, NetworkError, Raba7niClient, Raba7niError, Raba7niSDK, RateLimitError, ValidationError, WebhookHandler, calculateRetryDelay, deepClone, Raba7niSDK as default, formatDate, generateRequestId, isMemberJoinedWebhook, isMemberLeftWebhook, isPointsEarnedWebhook, isPointsRedeemedWebhook, isTransactionCreatedWebhook, isValidISODate, normalizePhoneNumber, parseWebhookPayload, sanitizeString, validateAmount, validateCardId, validateEmail, validateName, verifyWebhookSignature };
+export type { ApiError, ApiResponse, Card, CardRelationship, FindOrCreateMemberRequest, FindOrCreateMemberResponse, Member, MemberDetailsRequest, MemberDetailsResponse, MemberJoinedWebhookData, MemberLeftWebhookData, Order, OrderItem, OrderResponse, PointsEarnedWebhookData, PointsRedeemedWebhookData, Raba7niConfig, RateLimitInfo, Scope, Transaction, TransactionCreatedWebhookData, ValidateMemberRequest, ValidateMemberResponse, WebhookEvent, WebhookPayload };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGnC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,2BAA2B,EAC5B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,cAAc,EACd,cAAc,EACd,YAAY,EACZ,cAAc,EACd,SAAS,EACT,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,UAAU,EACX,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,aAAa,EACb,WAAW,EACX,QAAQ,EACR,aAAa,EACb,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,KAAK,EACL,SAAS,EACT,aAAa,EACb,IAAI,EACJ,MAAM,EACN,gBAAgB,EAChB,WAAW,EACX,KAAK,EACL,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,6BAA6B,EAC9B,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,YAAY,EACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,UAAU,IAAI,OAAO,EAAE,MAAM,OAAO,CAAC"}