Subscriptions Manager

Appearance

Data Models ​

Reference for data structures returned by the API.

Plan ​

typescript
interface Plan {
  id: string
  wallet: string
  name: string
  description?: string
  amount_sats: number
  interval: 'weekly' | 'monthly' | 'yearly'
  trial_days: number
  grace_period_days: number
  // Payment method flags
  allow_lightning: boolean
  allow_onchain: boolean
  allow_nwc: boolean         // NWC automatic payments
  allow_stripe: boolean      // Cards, Apple Pay, Google Pay
  allow_paypal: boolean      // PayPal payments
  // Optional configuration
  watchonly_wallet_id?: string
  stripe_account_id?: string
  paypal_merchant_id?: string
  created_at: number
  updated_at: number
  is_deleted: boolean
}

Subscription ​

typescript
interface Subscription {
  id: string
  plan_id: string
  subscriber_id: string
  status: SubscriptionStatus
  current_period_start: number
  current_period_end: number
  trial_end?: number
  cancelled_at?: number
  created_at: number
  updated_at: number
}

type SubscriptionStatus =
  | 'pending'
  | 'active'
  | 'paused'
  | 'past_due'
  | 'payment_failed'
  | 'cancelled'
  | 'expired'

Subscriber ​

typescript
interface Subscriber {
  id: string
  email?: string
  telegram?: string
  nostr?: string
  name?: string
  access_token: string
  created_at: number
}

Payment ​

typescript
interface Payment {
  id: string
  subscription_id: string
  amount_sats: number
  amount_fiat?: number        // For Stripe/PayPal payments
  currency?: string           // 'usd', 'eur', etc.
  status: PaymentStatus
  payment_method: PaymentMethod
  // Bitcoin-specific
  payment_request?: string    // Lightning invoice
  payment_hash?: string       // Lightning payment hash
  onchain_address?: string    // On-chain address
  onchain_txid?: string       // On-chain transaction ID
  // Fiat-specific
  stripe_payment_id?: string  // Stripe payment intent ID
  paypal_order_id?: string    // PayPal order ID
  created_at: number
  paid_at?: number
}

type PaymentMethod =
  | 'lightning'    // Lightning Network
  | 'onchain'      // On-chain Bitcoin
  | 'nwc'          // NWC automatic payment
  | 'stripe'       // Stripe (cards, Apple Pay, Google Pay)
  | 'paypal'       // PayPal

type PaymentStatus = 'pending' | 'paid' | 'failed' | 'expired'

NWC Models ​

Models for Nostr Wallet Connect integration.

NWC Validate Request ​

typescript
interface NWCValidateRequest {
  nwc_string: string  // The full NWC connection string
}

NWC Validate Response ​

typescript
interface NWCValidateResponse {
  valid: boolean
  error?: string  // Human-readable error if invalid
}

NWC Subscription Create ​

typescript
interface NWCSubscriptionCreate {
  plan_id: string
  email?: string
  name?: string
  nwc_connection_string: string
  contact_preference?: 'email' | 'telegram' | 'nostr'
}

NWC Subscription Response ​

typescript
interface NWCSubscriptionResponse {
  subscription_id: string
  status: 'active' | 'pending'
  message: string
  error_code?: string  // Only if payment failed
}

NWC Connection ​

Internal model for stored NWC connections:

typescript
interface NWCConnection {
  id: string
  subscriber_id: string
  wallet_pubkey: string      // First 8 chars shown to user
  relay_url: string
  max_amount_sats?: number
  is_active: boolean
  last_used_at?: number
  last_error?: string
  consecutive_failures: number
  created_at: number
  updated_at?: number
}

Webhook Event ​

typescript
interface WebhookEvent {
  event: string
  timestamp: number
  data: {
    subscription_id: string
    plan_id: string
    plan_name: string
    subscriber_email?: string
    subscriber_name?: string
    status: string
    amount_sats?: number
    [key: string]: any
  }
}

Timestamps ​

All timestamps are Unix timestamps (seconds since epoch).

javascript
// Convert to Date
const date = new Date(timestamp * 1000)

// Current timestamp
const now = Math.floor(Date.now() / 1000)