@stacksjs/types 0.70.23 → 0.70.26

package/src/payments.ts

@@ -1,32 +1,81 @@
+/**
+ * Payment Types
+ *
+ * Type definitions for the payments module.
+ */
+
 import type Stripe from 'stripe'
 
+// =============================================================================
+// Configuration Types
+// =============================================================================
+
 export interface PaymentOptions {
+  /**
+   * Payment provider
+   */
   driver: 'stripe'
 
-  stripe: {
-    publishableKey: string
-    secretKey: string
-  }
+  /**
+   * Stripe configuration
+   */
+  stripe: StripeConfig
+
+  /**
+   * Default currency (ISO 4217 code)
+   */
+  currency?: string
+
+  /**
+   * Webhook configuration
+   */
+  webhook?: WebhookConfig
 }
 
-export type PaymentConfig = Partial<PaymentOptions>
+export interface StripeConfig {
+  /**
+   * Stripe publishable key (client-side)
+   */
+  publishableKey: string
 
-export interface ChargeOptions {
-  currency?: string
-  source?: string
-  description?: string
-  chargeId?: string
-  limit?: number
-  metadata?: object
-  searchOptions: {
-    query?: string
-    limit?: number
-  }
+  /**
+   * Stripe secret key (server-side)
+   */
+  secretKey: string
+
+  /**
+   * Stripe API version
+   */
+  apiVersion?: string
+
+  /**
+   * Webhook signing secret
+   */
+  webhookSecret?: string
 }
 
+export interface WebhookConfig {
+  /**
+   * Webhook endpoint secret
+   */
+  secret: string
+
+  /**
+   * Tolerance in seconds for webhook timestamp verification
+   */
+  tolerance?: number
+}
+
+export type PaymentConfig = Partial<PaymentOptions>
+
+// =============================================================================
+// Customer Types
+// =============================================================================
+
 export interface StripeCustomerOptions {
   address?: {
     line1?: string
+    line2?: string
     city?: string
     state?: string
     postal_code?: string
@@ -43,12 +92,12 @@ export interface CustomerOptions {
   description?: string
   address?: string
   email?: string
-  metadata?: object
+  metadata?: Record<string, string>
   name?: string
   payment_method?: string
-  shipping: string
+  shipping?: ShippingInfo
   listOptions?: {
-    created?: object
+    created?: Record<string, unknown>
     ending_before?: string
     limit?: number
     starting_after?: string
@@ -61,9 +110,291 @@ export interface CustomerOptions {
   }
 }
 
+export interface ShippingInfo {
+  address: {
+    line1: string
+    line2?: string
+    city?: string
+    state?: string
+    postal_code?: string
+    country?: string
+  }
+  name: string
+  phone?: string
+}
+
+// =============================================================================
+// Charge Types
+// =============================================================================
+
+export interface ChargeOptions {
+  currency?: string
+  source?: string
+  description?: string
+  chargeId?: string
+  limit?: number
+  metadata?: Record<string, string>
+  searchOptions?: {
+    query?: string
+    limit?: number
+  }
+}
+
+export interface ChargeResult {
+  id: string
+  amount: number
+  currency: string
+  status: 'succeeded' | 'pending' | 'failed'
+  paymentMethod?: string
+  receiptUrl?: string
+  refunded: boolean
+  refundedAmount?: number
+}
+
+// =============================================================================
+// Checkout Types
+// =============================================================================
+
+export interface CheckoutLineItem {
+  priceId: string
+  quantity: number
+}
+
+export interface CheckoutOptions extends Partial<Stripe.Checkout.SessionCreateParams> {
+  /**
+   * Enable automatic tax calculation
+   */
+  enableTax?: boolean
+
+  /**
+   * Allow promotion codes
+   */
+  allowPromotions?: boolean
+}
+
+export interface CheckoutSessionResult {
+  id: string
+  url: string | null
+  status: string
+  customerId?: string
+  subscriptionId?: string
+  paymentIntentId?: string
+}
+
+// =============================================================================
+// Subscription Types
+// =============================================================================
+
+export interface SubscriptionOptions {
+  /**
+   * Subscription type/name
+   */
+  type: string
+
+  /**
+   * Price lookup key
+   */
+  lookupKey: string
+
+  /**
+   * Trial period in days
+   */
+  trialDays?: number
+
+  /**
+   * Coupon or promotion code
+   */
+  coupon?: string
+
+  /**
+   * Additional metadata
+   */
+  metadata?: Record<string, string>
+}
+
+export interface SubscriptionResult {
+  id: string
+  status: SubscriptionStatus
+  currentPeriodEnd: Date
+  cancelAtPeriodEnd: boolean
+  items: SubscriptionItem[]
+  latestInvoiceId?: string
+}
+
+export type SubscriptionStatus =
+  | 'active'
+  | 'canceled'
+  | 'incomplete'
+  | 'incomplete_expired'
+  | 'past_due'
+  | 'paused'
+  | 'trialing'
+  | 'unpaid'
+
+export interface SubscriptionItem {
+  id: string
+  priceId: string
+  productId: string
+  quantity: number
+}
+
+// =============================================================================
+// Invoice Types
+// =============================================================================
+
+export interface InvoiceResult {
+  id: string
+  number: string | null
+  status: InvoiceStatus
+  amountDue: number
+  amountPaid: number
+  currency: string
+  dueDate: Date | null
+  paidAt: Date | null
+  hostedInvoiceUrl: string | null
+  pdfUrl: string | null
+}
+
+export type InvoiceStatus =
+  | 'draft'
+  | 'open'
+  | 'paid'
+  | 'uncollectible'
+  | 'void'
+
+// =============================================================================
+// Payment Method Types
+// =============================================================================
+
+export interface PaymentMethodResult {
+  id: string
+  type: PaymentMethodType
+  card?: CardDetails
+  isDefault: boolean
+}
+
+export type PaymentMethodType =
+  | 'card'
+  | 'bank_account'
+  | 'sepa_debit'
+  | 'ideal'
+  | 'sofort'
+  | 'giropay'
+
+export interface CardDetails {
+  brand: string
+  last4: string
+  expMonth: number
+  expYear: number
+  funding: 'credit' | 'debit' | 'prepaid' | 'unknown'
+}
+
+// =============================================================================
+// Product & Price Types
+// =============================================================================
+
+export interface ProductOptions {
+  name: string
+  description?: string
+  images?: string[]
+  metadata?: Record<string, string>
+  active?: boolean
+}
+
+export interface PriceOptions {
+  productId: string
+  unitAmount: number
+  currency?: string
+  recurring?: {
+    interval: 'day' | 'week' | 'month' | 'year'
+    intervalCount?: number
+  }
+  lookupKey?: string
+  metadata?: Record<string, string>
+}
+
+// =============================================================================
+// Coupon Types
+// =============================================================================
+
+export interface CouponOptions {
+  id?: string
+  name?: string
+  percentOff?: number
+  amountOff?: number
+  currency?: string
+  duration: 'forever' | 'once' | 'repeating'
+  durationInMonths?: number
+  maxRedemptions?: number
+  redeemBy?: Date
+}
+
+export interface PromotionCodeOptions {
+  couponId: string
+  code: string
+  maxRedemptions?: number
+  expiresAt?: Date
+  firstTimeTransaction?: boolean
+  minimumAmount?: number
+  minimumAmountCurrency?: string
+}
+
+// =============================================================================
+// Webhook Types
+// =============================================================================
+
+export type WebhookEventType =
+  | 'payment_intent.succeeded'
+  | 'payment_intent.payment_failed'
+  | 'payment_intent.created'
+  | 'payment_intent.canceled'
+  | 'customer.subscription.created'
+  | 'customer.subscription.updated'
+  | 'customer.subscription.deleted'
+  | 'customer.subscription.trial_will_end'
+  | 'customer.created'
+  | 'customer.updated'
+  | 'customer.deleted'
+  | 'invoice.paid'
+  | 'invoice.payment_failed'
+  | 'invoice.finalized'
+  | 'invoice.created'
+  | 'checkout.session.completed'
+  | 'checkout.session.expired'
+  | 'charge.succeeded'
+  | 'charge.failed'
+  | 'charge.refunded'
+  | 'charge.dispute.created'
+  | 'charge.dispute.closed'
+  | 'payment_method.attached'
+  | 'payment_method.detached'
+  | 'setup_intent.succeeded'
+  | 'setup_intent.setup_failed'
+
+export interface WebhookEvent<T = unknown> {
+  id: string
+  type: WebhookEventType
+  data: {
+    object: T
+    previousAttributes?: Partial<T>
+  }
+  created: number
+  livemode: boolean
+}
+
+export interface WebhookHandlerResult {
+  handled: boolean
+  eventType: string
+  error?: string
+}
+
+// =============================================================================
+// Dispute Types
+// =============================================================================
+
 export interface DisputeOptions {
   dp_id?: string
-  metadata?: object
+  metadata?: Record<string, string>
   listOptions?: {
     charge?: string
     payment_intent?: string
@@ -74,10 +405,14 @@ export interface DisputeOptions {
   }
 }
 
+// =============================================================================
+// Event Types
+// =============================================================================
+
 export interface EventOptions {
   event_id?: string
   listOptions?: {
-    created?: object
+    created?: Record<string, unknown>
     delivery_success?: boolean
     ending_before?: string
     limit?: number
@@ -86,12 +421,20 @@ export interface EventOptions {
   }
 }
 
-export interface CheckoutLineItem {
-  priceId: string
-  quantity: number
+// =============================================================================
+// Utility Types
+// =============================================================================
+
+export interface PaginatedResult<T> {
+  data: T[]
+  hasMore: boolean
+  totalCount?: number
 }
 
-export interface CheckoutOptions extends Partial<Stripe.Checkout.SessionCreateParams> {
-  enableTax?: boolean
-  allowPromotions?: boolean
+export interface AmountBreakdown {
+  subtotal: number
+  tax: number
+  discount: number
+  total: number
+  currency: string
 }

package/src/phone.ts

@@ -0,0 +1,62 @@
+/**
+ * Phone/Voice Service Configuration Types
+ * Powered by Amazon Connect
+ */
+
+export interface PhoneNumberConfig {
+  type: 'TOLL_FREE' | 'DID' | 'UIFN'
+  countryCode: string
+  description?: string
+  contactFlowId?: string
+  notifyOnCall?: string[] // team member emails/phones
+}
+
+export interface PhoneNotificationConfig {
+  enabled: boolean
+  channels: ('email' | 'sms' | 'slack' | 'webhook')[]
+  webhookUrl?: string
+  slackChannel?: string
+}
+
+export interface BusinessHoursSchedule {
+  day: 'SUNDAY' | 'MONDAY' | 'TUESDAY' | 'WEDNESDAY' | 'THURSDAY' | 'FRIDAY' | 'SATURDAY'
+  start: string // HH:MM format
+  end: string // HH:MM format
+}
+
+export interface BusinessHoursConfig {
+  timezone: string
+  schedule: BusinessHoursSchedule[]
+}
+
+export interface VoicemailConfig {
+  enabled: boolean
+  transcription: boolean
+  maxDurationSeconds: number
+  greeting?: string
+}
+
+export interface PhoneInstanceConfig {
+  alias: string
+  inboundCallsEnabled: boolean
+  outboundCallsEnabled: boolean
+}
+
+export interface PhoneNotificationsConfig {
+  incomingCall?: PhoneNotificationConfig
+  missedCall?: PhoneNotificationConfig
+  voicemail?: PhoneNotificationConfig
+}
+
+export interface PhoneOptions {
+  enabled: boolean
+  provider: 'connect' // Amazon Connect
+
+  instance?: PhoneInstanceConfig
+  phoneNumbers: PhoneNumberConfig[]
+  notifications: PhoneNotificationsConfig
+  voicemail: VoicemailConfig
+  businessHours?: BusinessHoursConfig
+}
+
+export type PhoneConfig = Partial<PhoneOptions>

package/src/push.ts

@@ -1,3 +1,64 @@
+/**
+ * Push Notification Configuration Types
+ * Supports APNs (Apple) and FCM (Firebase/Google)
+ */
+
+/**
+ * Apple Push Notification Service (APNs) configuration
+ */
+export interface APNsProviderConfig {
+  /** APNs Key ID from Apple Developer Portal */
+  keyId: string
+  /** Team ID from Apple Developer Portal */
+  teamId: string
+  /** Path to the private key file (p8) or the key content */
+  privateKey: string
+  /** iOS app bundle ID (e.g., com.example.app) */
+  bundleId: string
+  /** Use production APNs server (default: false for sandbox) */
+  production?: boolean
+}
+
+/**
+ * Firebase Cloud Messaging (FCM) configuration
+ */
+export interface FCMProviderConfig {
+  /** Firebase project ID */
+  projectId: string
+  /** Service account client email */
+  clientEmail: string
+  /** Service account private key (PEM format) */
+  privateKey: string
+}
+
+/**
+ * Push notification provider configuration
+ */
+export interface PushProviderOptions {
+  /** APNs configuration (optional) */
+  apns?: APNsProviderConfig
+  /** FCM configuration (optional) */
+  fcm?: FCMProviderConfig
+}
+
+/**
+ * Push notification options
+ */
+export interface PushOptions {
+  /** Enable push notifications */
+  enabled: boolean
+  /** Default provider to use */
+  defaultProvider?: 'apns' | 'fcm'
+  /** Provider configurations */
+  providers: PushProviderOptions
+}
+
+/**
+ * Push notification configuration type
+ */
+export type PushConfig = Partial<PushOptions>
+
+// Legacy types for backwards compatibility
 export interface FCMPushNotificationOptions {
   eventName: string
   to: {
@@ -34,3 +95,49 @@ export interface ExpoPushNotificationOptions {
     mutableContent: boolean
   }
 }
+
+/**
+ * Result from a push notification operation
+ */
+export interface PushResult {
+  /** Whether the operation was successful */
+  success: boolean
+  /** The provider that handled the notification */
+  provider: string
+  /** Human-readable message about the result */
+  message: string
+  /** Message ID returned from the provider */
+  messageId?: string
+  /** Additional provider-specific data */
+  data?: Record<string, any>
+}
+
+/**
+ * Push message structure
+ */
+export interface PushMessage {
+  /** Device token(s) to send to */
+  to: string | string[]
+  /** Notification title */
+  title?: string
+  /** Notification body */
+  body: string
+  /** Additional data payload */
+  data?: Record<string, any>
+  /** Badge count */
+  badge?: number
+  /** Sound to play */
+  sound?: 'default' | null
+  /** Message priority */
+  priority?: 'default' | 'normal' | 'high'
+}
+
+/**
+ * Push ticket from Expo
+ */
+export interface PushTicket {
+  id?: string
+  status: 'ok' | 'error'
+  message?: string
+  details?: Record<string, any>
+}