livepasses 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,677 @@
+/**
+ * Standard API response envelope.
+ * All Livepasses API endpoints return this structure.
+ */
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: ApiError;
+    message?: string;
+    meta?: ResponseMetadata;
+}
+/**
+ * Paginated API response envelope.
+ */
+interface ApiPagedResponse<T> {
+    success: boolean;
+    items: T[];
+    pagination: PaginationMetadata;
+    error?: ApiError;
+    message?: string;
+    meta?: ResponseMetadata;
+}
+interface PaginationMetadata {
+    currentPage: number;
+    pageSize: number;
+    totalPages: number;
+    totalItems: number;
+}
+interface ResponseMetadata {
+    traceId?: string;
+    processingTimeMs?: number;
+    timestamp?: string;
+}
+interface ApiError {
+    message: string;
+    code: string;
+    details?: string;
+    timestamp?: string;
+    traceId?: string;
+}
+/**
+ * Base parameters for paginated list queries.
+ */
+interface PagedParams {
+    page?: number;
+    pageSize?: number;
+    searchTerm?: string;
+    sortBy?: string;
+    sortDescending?: boolean;
+}
+/**
+ * All API error codes returned by the Livepasses API.
+ * Mirrors ApiErrorCodes.cs 1:1.
+ */
+declare const ApiErrorCodes: {
+    readonly GENERAL_ERROR: "GENERAL_ERROR";
+    readonly INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly INVALID_API_KEY: "INVALID_API_KEY";
+    readonly API_KEY_EXPIRED: "API_KEY_EXPIRED";
+    readonly API_KEY_REVOKED: "API_KEY_REVOKED";
+    readonly INSUFFICIENT_PERMISSIONS: "INSUFFICIENT_PERMISSIONS";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly REQUIRED_FIELD_MISSING: "REQUIRED_FIELD_MISSING";
+    readonly INVALID_FIELD_VALUE: "INVALID_FIELD_VALUE";
+    readonly INVALID_FIELD_FORMAT: "INVALID_FIELD_FORMAT";
+    readonly FIELD_TOO_LONG: "FIELD_TOO_LONG";
+    readonly FIELD_TOO_SHORT: "FIELD_TOO_SHORT";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly RESOURCE_EXISTS: "RESOURCE_EXISTS";
+    readonly RESOURCE_LOCKED: "RESOURCE_LOCKED";
+    readonly RESOURCE_EXPIRED: "RESOURCE_EXPIRED";
+    readonly BUSINESS_RULE_VIOLATION: "BUSINESS_RULE_VIOLATION";
+    readonly INSUFFICIENT_FUNDS: "INSUFFICIENT_FUNDS";
+    readonly QUOTA_EXCEEDED: "QUOTA_EXCEEDED";
+    readonly OPERATION_NOT_ALLOWED: "OPERATION_NOT_ALLOWED";
+    readonly SUBSCRIPTION_REQUIRED: "SUBSCRIPTION_REQUIRED";
+    readonly FEATURE_NOT_AVAILABLE: "FEATURE_NOT_AVAILABLE";
+    readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
+    readonly TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS";
+    readonly API_QUOTA_EXCEEDED: "API_QUOTA_EXCEEDED";
+    readonly TENANT_NOT_FOUND: "TENANT_NOT_FOUND";
+    readonly PARTNERSHIP_NOT_FOUND: "PARTNERSHIP_NOT_FOUND";
+    readonly PARTNERSHIP_INACTIVE: "PARTNERSHIP_INACTIVE";
+    readonly TENANT_SUSPENDED: "TENANT_SUSPENDED";
+    readonly PARTNERSHIP_TIER_LIMIT_REACHED: "PARTNERSHIP_TIER_LIMIT_REACHED";
+    readonly TEMPLATE_NOT_FOUND: "TEMPLATE_NOT_FOUND";
+    readonly PASS_NOT_FOUND: "PASS_NOT_FOUND";
+    readonly PASS_EXPIRED: "PASS_EXPIRED";
+    readonly PASS_ALREADY_USED: "PASS_ALREADY_USED";
+    readonly INVALID_PASS_FORMAT: "INVALID_PASS_FORMAT";
+    readonly TEMPLATE_INACTIVE: "TEMPLATE_INACTIVE";
+    readonly EXTERNAL_SERVICE_ERROR: "EXTERNAL_SERVICE_ERROR";
+    readonly PAYMENT_SERVICE_ERROR: "PAYMENT_SERVICE_ERROR";
+    readonly EMAIL_SERVICE_ERROR: "EMAIL_SERVICE_ERROR";
+    readonly SMS_SERVICE_ERROR: "SMS_SERVICE_ERROR";
+    readonly APPLE_WALLET_ERROR: "APPLE_WALLET_ERROR";
+    readonly GOOGLE_WALLET_ERROR: "GOOGLE_WALLET_ERROR";
+};
+type ApiErrorCode = (typeof ApiErrorCodes)[keyof typeof ApiErrorCodes];
+
+interface HttpClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+    maxRetries: number;
+}
+/**
+ * Internal HTTP client that wraps native fetch with:
+ * - API key injection
+ * - ApiResponse<T> envelope unwrapping
+ * - Typed error mapping
+ * - Automatic retry with exponential backoff for 429 and 5xx
+ */
+declare class HttpClient {
+    private readonly config;
+    constructor(config: HttpClientConfig);
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    /**
+     * Like get() but returns the full paginated response instead of unwrapping.
+     */
+    getPaged<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<ApiPagedResponse<T>>;
+    private request;
+    private requestPaged;
+    private fetchWithRetry;
+    private buildUrl;
+}
+
+/**
+ * Pass type definitions mirroring the Livepasses API DTOs.
+ */
+/** Parameters for generating passes via POST /api/passes/generate */
+interface GeneratePassesParams {
+    /** Template ID to generate passes from */
+    templateId: string;
+    /** Business context for pass generation (template-type specific) */
+    businessContext?: BusinessContext;
+    /** Pass recipients with business data */
+    passes: PassRecipient[];
+    /** Generation options */
+    options?: PassGenerationOptions;
+}
+/** Business context for pass generation - contains instance-specific data */
+interface BusinessContext {
+    event?: EventContext;
+    loyalty?: LoyaltyContext;
+    coupon?: CouponContext;
+}
+interface EventContext {
+    eventName?: string;
+    eventDate?: string;
+    doorsOpen?: string;
+    specialAnnouncement?: string;
+}
+interface LoyaltyContext {
+    programUpdate?: string;
+    seasonalMessage?: string;
+}
+interface CouponContext {
+    campaignName?: string;
+    specialMessage?: string;
+    promotionStartDate?: string;
+    promotionEndDate?: string;
+}
+/** A single pass recipient */
+interface PassRecipient {
+    customer: CustomerInfo;
+    businessData: BusinessData;
+    personalizations?: PersonalizationData;
+}
+interface CustomerInfo {
+    email?: string;
+    firstName: string;
+    lastName: string;
+    phone?: string;
+    preferredLanguage?: string;
+}
+/** Business data that adapts based on template type */
+interface BusinessData {
+    sectionInfo?: string;
+    rowInfo?: string;
+    seatNumber?: string;
+    gateInfo?: string;
+    confirmationCode?: string;
+    ticketType?: string;
+    price?: number;
+    currency?: string;
+    membershipNumber?: string;
+    currentPoints?: number;
+    memberTier?: string;
+    lifetimePoints?: number;
+    accountBalance?: number;
+    memberSince?: string;
+    favoriteStore?: string;
+    promoCode?: string;
+    campaignId?: string;
+    customerSegment?: string;
+    maxUsageCount?: number;
+    sourceChannel?: string;
+}
+interface PersonalizationData {
+    dietaryRestrictions?: string;
+    accessibilityNeeds?: string;
+    customFields?: Record<string, string>;
+}
+interface PassGenerationOptions {
+    /** Delivery method: auto | email | sms | whatsapp | webhook | return_urls */
+    deliveryMethod?: string;
+    /** Generate for all platforms (Apple + Google). Defaults to true. */
+    generateForAllPlatforms?: boolean;
+}
+/** Result from pass generation */
+interface PassGenerationResult {
+    batchId: string;
+    templateId: string;
+    generatedAt: string;
+    totalPasses: number;
+    /** When true, poll getBatchStatus() for results */
+    isAsyncProcessing: boolean;
+    batchOperation?: BatchOperationInfo;
+    /** Populated for sync generation, empty for async */
+    passes: GeneratedPass[];
+    delivery?: PassDeliveryResult;
+    businessMetrics?: BusinessMetrics;
+}
+interface BatchOperationInfo {
+    id: string;
+    status: string;
+    totalRecipients: number;
+    passesGenerated: number;
+    generationFailures: number;
+    progressPercentage: number;
+    estimatedCompletion?: string;
+    statusPollUrl: string;
+}
+interface GeneratedPass {
+    id: string;
+    customerEmail?: string;
+    confirmationCode?: string;
+    platforms: PassPlatforms;
+    businessData: UnifiedBusinessData;
+    qrCode?: string;
+    status: string;
+    analytics?: AnalyticsInfo;
+}
+interface PassPlatforms {
+    apple: PassPlatform;
+    google: PassPlatform;
+}
+interface PassPlatform {
+    available: boolean;
+    addToWalletUrl?: string;
+    passUrl?: string;
+    jwtToken?: string;
+    features: string[];
+}
+interface UnifiedBusinessData {
+    section?: string;
+    row?: string;
+    seat?: string;
+    gate?: string;
+    ticketType?: string;
+    formattedPrice?: string;
+    membershipNumber?: string;
+    currentPoints?: number;
+    memberTier?: string;
+    formattedBalance?: string;
+    promoCode?: string;
+    discountDescription?: string;
+    validityDescription?: string;
+}
+interface PassDeliveryResult {
+    method: string;
+    status: string;
+    sentAt: string;
+    details: DeliveryDetail[];
+}
+interface DeliveryDetail {
+    recipient?: string;
+    status: string;
+}
+interface BusinessMetrics {
+    totalRevenue?: number;
+    averageTicketPrice?: number;
+    seatDistribution?: Record<string, number>;
+    tierDistribution?: Record<string, number>;
+    revenueByCategory?: Record<string, number>;
+}
+interface AnalyticsInfo {
+    trackingId: string;
+    engagementUrl: string;
+}
+interface PassLookupResult {
+    passId: string;
+    passNumber: string;
+    templateId: string;
+    templateName: string;
+    templateType: string;
+    holderName?: string;
+    holderEmail?: string;
+    status: string;
+    isValid: boolean;
+    canBeRedeemed: boolean;
+    isExpired: boolean;
+    validFrom?: string;
+    validUntil?: string;
+    redeemedAt?: string;
+    generatedAt: string;
+}
+interface PassValidationResult {
+    passId: string;
+    passNumber: string;
+    status: string;
+    canBeRedeemed: boolean;
+    isExpired: boolean;
+    validationMessage: string;
+    templateType: string;
+    holderName?: string;
+    holderEmail?: string;
+    validFrom?: string;
+    validUntil?: string;
+    verificationMethods: string[];
+}
+interface PassRedemptionResult {
+    passId: string;
+    passNumber: string;
+    redeemedAt: string;
+    redemptionMethod: string;
+    previousStatus: string;
+    newStatus: string;
+    alreadyRedeemed: boolean;
+}
+interface RedemptionLocation {
+    name?: string;
+    latitude?: number;
+    longitude?: number;
+}
+interface RedeemPassParams {
+    location?: RedemptionLocation;
+    notes?: string;
+}
+interface CheckInParams {
+    location?: RedemptionLocation;
+    notes?: string;
+}
+interface RedeemCouponParams {
+    location?: RedemptionLocation;
+    notes?: string;
+}
+interface LoyaltyTransactionParams {
+    /** Transaction type: earn | spend */
+    transactionType: 'earn' | 'spend';
+    points: number;
+    description?: string;
+}
+interface UpdatePassParams {
+    businessData?: Partial<BusinessData>;
+    businessContext?: BusinessContext;
+}
+interface BulkUpdatePassesParams {
+    passIds: string[];
+    businessData?: Partial<BusinessData>;
+    businessContext?: BusinessContext;
+}
+interface BatchStatusResult {
+    id: string;
+    status: string;
+    totalRecipients: number;
+    passesGenerated: number;
+    passesDelivered: number;
+    generationFailures: number;
+    deliveryFailures: number;
+    progressPercentage: number;
+    startedAt?: string;
+    completedAt?: string;
+    estimatedCompletion?: string;
+    errorMessage?: string;
+    isCompleted: boolean;
+    isActive: boolean;
+    statistics?: BatchStatistics;
+    generatedPasses?: GeneratedPassSummary[];
+}
+interface BatchStatistics {
+    averageGenerationTimeSeconds: number;
+    generationSuccessRate: number;
+    deliverySuccessRate: number;
+    mostCommonError?: string;
+    totalDuration?: string;
+}
+interface GeneratedPassSummary {
+    id: string;
+    passNumber: string;
+    holderEmail?: string;
+    holderName?: string;
+    status: string;
+    hasApplePass: boolean;
+    hasGooglePass: boolean;
+    generatedAt: string;
+}
+interface ListPassesParams {
+    templateId?: string;
+    status?: string;
+    platform?: string;
+    page?: number;
+    pageSize?: number;
+    searchTerm?: string;
+    sortBy?: string;
+    sortDescending?: boolean;
+}
+interface GlobalPassDto {
+    id: string;
+    serialNumber: string;
+    platform: string;
+    status: string;
+    generatedAt: string;
+    redeemedAt?: string;
+    validUntil?: string;
+    holderEmail?: string;
+    templateId: string;
+    templateName: string;
+    templateType: string;
+}
+interface LookupPassParams {
+    passId?: string;
+    passNumber?: string;
+}
+interface GenerateAndWaitOptions {
+    /** Polling interval in milliseconds. Default: 2000 */
+    pollInterval?: number;
+    /** Maximum number of poll attempts. Default: 150 (5 minutes at 2s interval) */
+    maxAttempts?: number;
+    /** Callback invoked on each poll with current batch status */
+    onProgress?: (status: BatchStatusResult) => void;
+}
+
+declare class PassesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Generate passes for one or more recipients.
+     * For a single recipient, the pass is returned synchronously.
+     * For multiple recipients, returns immediately with a batchId — poll with `getBatchStatus()`.
+     *
+     * @see generateAndWait for an auto-polling helper
+     */
+    generate(params: GeneratePassesParams): Promise<PassGenerationResult>;
+    /**
+     * Generate passes and automatically poll until the batch is complete.
+     * This is the recommended method for most use cases.
+     *
+     * For sync generation (1 recipient), returns immediately.
+     * For async batches (>1 recipient), polls `getBatchStatus()` until done.
+     */
+    generateAndWait(params: GeneratePassesParams, options?: GenerateAndWaitOptions): Promise<PassGenerationResult>;
+    /**
+     * List passes (paginated).
+     */
+    list(params?: ListPassesParams): Promise<ApiPagedResponse<GlobalPassDto>>;
+    /**
+     * Auto-paginate through all passes matching the given filters.
+     *
+     * @example
+     * ```ts
+     * for await (const pass of livepasses.passes.listAutoPaginate({ templateId: '...' })) {
+     *   console.log(pass.id);
+     * }
+     * ```
+     */
+    listAutoPaginate(params?: Omit<ListPassesParams, 'page'>): AsyncGenerator<GlobalPassDto, void, undefined>;
+    /**
+     * Look up a pass by ID or pass number.
+     */
+    lookup(params: LookupPassParams): Promise<PassLookupResult>;
+    /**
+     * Validate a pass before redemption.
+     */
+    validate(passId: string): Promise<PassValidationResult>;
+    /**
+     * Update a pass's business data.
+     */
+    update(passId: string, params: UpdatePassParams): Promise<void>;
+    /**
+     * Bulk update multiple passes.
+     */
+    bulkUpdate(params: BulkUpdatePassesParams): Promise<void>;
+    /**
+     * Redeem a pass (generic redemption).
+     */
+    redeem(passId: string, params?: RedeemPassParams): Promise<PassRedemptionResult>;
+    /**
+     * Check in an event pass.
+     */
+    checkIn(passId: string, params?: CheckInParams): Promise<PassRedemptionResult>;
+    /**
+     * Redeem a coupon pass.
+     */
+    redeemCoupon(passId: string, params?: RedeemCouponParams): Promise<PassRedemptionResult>;
+    /**
+     * Earn or spend loyalty points.
+     */
+    loyaltyTransact(passId: string, params: LoyaltyTransactionParams): Promise<PassRedemptionResult>;
+    /**
+     * Get the status of a batch pass generation operation.
+     */
+    getBatchStatus(batchId: string): Promise<BatchStatusResult>;
+}
+
+interface TemplateListItem {
+    id: string;
+    name: string;
+    description?: string;
+    type: string;
+    status: string;
+    passCount: number;
+    createdAt: string;
+    updatedAt?: string;
+}
+interface TemplateDetail extends TemplateListItem {
+    businessFeatures?: Record<string, unknown>;
+    platformSupport?: Record<string, unknown>;
+    mediaConfiguration?: Record<string, unknown>;
+}
+interface ListTemplatesParams extends PagedParams {
+    type?: string;
+    status?: string;
+}
+interface CreateTemplateParams {
+    name: string;
+    description?: string;
+    businessFeatures: Record<string, unknown>;
+    requiredMedia?: string[];
+}
+interface UpdateTemplateParams {
+    name?: string;
+    description?: string;
+    businessFeatures?: Record<string, unknown>;
+}
+
+declare class TemplatesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List templates (paginated).
+     */
+    list(params?: ListTemplatesParams): Promise<ApiPagedResponse<TemplateListItem>>;
+    /**
+     * Get a single template by ID.
+     */
+    get(templateId: string): Promise<TemplateDetail>;
+    /**
+     * Create a new template.
+     */
+    create(params: CreateTemplateParams): Promise<TemplateDetail>;
+    /**
+     * Update a template.
+     */
+    update(templateId: string, params: UpdateTemplateParams): Promise<TemplateDetail>;
+    /**
+     * Activate a template for pass generation.
+     */
+    activate(templateId: string): Promise<void>;
+    /**
+     * Deactivate a template.
+     */
+    deactivate(templateId: string): Promise<void>;
+}
+
+interface Webhook {
+    id: string;
+    url: string;
+    events: WebhookEventType[];
+    isActive: boolean;
+    createdAt: string;
+    secret?: string;
+}
+interface CreateWebhookParams {
+    url: string;
+    events: WebhookEventType[];
+}
+type WebhookEventType = 'pass.generated' | 'pass.redeemed' | 'pass.updated' | 'pass.expired' | 'pass.checked_in' | 'batch.completed' | 'batch.failed';
+
+declare class WebhooksResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a webhook endpoint.
+     */
+    create(params: CreateWebhookParams): Promise<Webhook>;
+    /**
+     * List all registered webhooks.
+     */
+    list(): Promise<Webhook[]>;
+    /**
+     * Delete a webhook by ID.
+     */
+    delete(webhookId: string): Promise<void>;
+}
+
+interface LivepassesOptions {
+    /** API base URL. Default: https://api.livepasses.com */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 30000 */
+    timeout?: number;
+    /** Maximum number of retries for failed requests. Default: 3 */
+    maxRetries?: number;
+}
+/**
+ * Livepasses API client.
+ *
+ * @example
+ * ```ts
+ * import { Livepasses } from 'livepasses';
+ *
+ * const client = new Livepasses('lp_api_key_...');
+ * const result = await client.passes.generate({
+ *   templateId: 'template-id',
+ *   passes: [{
+ *     customer: { firstName: 'Jane', lastName: 'Doe', email: 'jane@example.com' },
+ *     businessData: { sectionInfo: 'A', rowInfo: '12', seatNumber: '5' },
+ *   }],
+ * });
+ * ```
+ */
+declare class Livepasses {
+    readonly passes: PassesResource;
+    readonly templates: TemplatesResource;
+    readonly webhooks: WebhooksResource;
+    constructor(apiKey: string, options?: LivepassesOptions);
+}
+
+/**
+ * Base error class for all Livepasses API errors.
+ * Contains the HTTP status code, API error code, and optional details.
+ */
+declare class LivepassesError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: string;
+    constructor(message: string, status: number, code: string, details?: string);
+}
+/** Thrown for 401 responses - invalid or missing API key */
+declare class AuthenticationError extends LivepassesError {
+    constructor(message: string, code: string, details?: string);
+}
+/** Thrown for validation errors (400) - invalid input data */
+declare class ValidationError extends LivepassesError {
+    constructor(message: string, code: string, details?: string);
+}
+/** Thrown for 403 responses - insufficient permissions */
+declare class ForbiddenError extends LivepassesError {
+    constructor(message: string, code: string, details?: string);
+}
+/** Thrown for 404 responses - resource not found */
+declare class NotFoundError extends LivepassesError {
+    constructor(message: string, code: string, details?: string);
+}
+/** Thrown for 429 responses - rate limit exceeded */
+declare class RateLimitError extends LivepassesError {
+    /** Seconds to wait before retrying, from Retry-After header */
+    readonly retryAfter?: number;
+    constructor(message: string, code: string, retryAfter?: number, details?: string);
+}
+/** Thrown when subscription quota is exceeded */
+declare class QuotaExceededError extends LivepassesError {
+    constructor(message: string, code: string, details?: string);
+}
+/** Thrown for business rule violations */
+declare class BusinessRuleError extends LivepassesError {
+    constructor(message: string, code: string, details?: string);
+}
+
+export { type AnalyticsInfo, type ApiError, type ApiErrorCode, ApiErrorCodes, type ApiPagedResponse, type ApiResponse, AuthenticationError, type BatchOperationInfo, type BatchStatistics, type BatchStatusResult, type BulkUpdatePassesParams, type BusinessContext, type BusinessData, type BusinessMetrics, BusinessRuleError, type CheckInParams, type CouponContext, type CreateTemplateParams, type CreateWebhookParams, type CustomerInfo, type DeliveryDetail, type EventContext, ForbiddenError, type GenerateAndWaitOptions, type GeneratePassesParams, type GeneratedPass, type GeneratedPassSummary, type GlobalPassDto, type ListPassesParams, type ListTemplatesParams, Livepasses, LivepassesError, type LivepassesOptions, type LookupPassParams, type LoyaltyContext, type LoyaltyTransactionParams, NotFoundError, type PagedParams, type PaginationMetadata, type PassDeliveryResult, type PassGenerationOptions, type PassGenerationResult, type PassLookupResult, type PassPlatform, type PassPlatforms, type PassRecipient, type PassRedemptionResult, type PassValidationResult, type PersonalizationData, QuotaExceededError, RateLimitError, type RedeemCouponParams, type RedeemPassParams, type RedemptionLocation, type ResponseMetadata, type TemplateDetail, type TemplateListItem, type UnifiedBusinessData, type UpdatePassParams, type UpdateTemplateParams, ValidationError, type Webhook, type WebhookEventType, Livepasses as default };