@tat-protocol/boxoffice

Purchase and sales protocol for TAT Protocol tokens.

Overview

The Boxoffice module provides two implementations:

$3

Implements the TAT Protocol Extensions specification section 4 (Booth Protocol) with official NWPC methods:
- booth.catalog - Browse available TATs
- booth.invoice - Request purchase invoice
- booth.pay - Submit payment
- booth.status - Check invoice status

Use this for spec-compliant implementations.

$3

Protocol-level SDK with pluggable payment providers, pricing engines, and custom business logic.

Use this for custom implementations with advanced features.

---

Installation

``bash
npm install @tat-protocol/boxoffice
`

Quick Start

$3

`typescript
import { BoxofficeServerSpec, CatalogItem } from '@tat-protocol/boxoffice';
import { NodeStorage } from '@tat-protocol/storage';

// Create spec-compliant booth
const boxoffice = await BoxofficeServerSpec.create({
storage: new NodeStorage({ path: './boxoffice' }),
keys: myKeys,
boxOfficeName: 'TATpay',
fee: 0.025, // 2.5% fee
relays: ['wss://relay.damus.io'],
supportedPaymentMethods: ['lightning', 'card']
});

// Add catalog items (per spec section 4.4)
const catalogItem: CatalogItem = {
id: 'premium-monthly',
issuer: forgePublicKey,
name: 'Premium Membership',
description: 'Monthly premium access',
price: {
amount: 5.0,
currency: 'USD'
},
tokenType: 'TAT',
duration: 2592000, // 30 days in seconds
supply: {
total: 0, // Unlimited
remaining: 0,
},
metadata: {
category: 'membership',
benefits: ['Exclusive content', 'Early access']
}
};

await boxoffice.addCatalogItem(catalogItem);

// Now clients can call:
// - booth.catalog
// - booth.invoice
// - booth.pay
// - booth.status
`

$3

`typescript
import { BoxofficeBase, TokenOrder, Receipt } from '@tat-protocol/boxoffice';

class MyBoxoffice extends BoxofficeBase {
// Implement how to fulfill orders after payment
protected async fulfillOrder(order: TokenOrder): Promise {
// Mint tokens via your forge
const tokens = await this.forge.mint({
recipient: order.buyerAddress,
quantity: order.quantity,
tokenType: order.tokenType
});

// Create receipt
return {
receiptId: receipt-${order.orderId},
orderId: order.orderId,
buyer: order.buyer,
payment: this.getPaymentForOrder(order.orderId),
tokens: tokens.map(t => t.toJWT()),
issuedAt: Date.now()
};
}

// Validate orders before creation
protected async validateOrder(order: Partial): Promise {
// Custom validation logic
// Check inventory, buyer eligibility, pricing, etc.
return true;
}
}
`

Implementing Payment Providers

`typescript
import { PaymentProvider, PaymentMethod } from '@tat-protocol/boxoffice';

class BitcoinPaymentProvider implements PaymentProvider {
readonly name = 'bitcoin';
readonly supportedMethods = [PaymentMethod.BITCOIN];

async initializePayment(payment: Payment) {
// Generate Bitcoin address
const address = await this.generateAddress();

return {
paymentId: payment.paymentId,
paymentAddress: address,
expiresAt: Date.now() + 3600000 // 1 hour
};
}

async verifyPayment(paymentId: string) {
// Check blockchain for payment
const tx = await this.checkBlockchain(paymentId);

return {
verified: tx.confirmed,
status: tx.confirmed ? 'COMPLETED' : 'PENDING',
transactionId: tx.hash,
completedAt: tx.confirmedAt
};
}

// Implement other PaymentProvider methods...
}
``

Core Interfaces

$3

Defines how payments are processed for different payment methods.

$3

Defines pricing strategies (fixed, dynamic, bulk discounts, etc.).

$3

Order structure for purchasing tokens.

$3

Cryptographically signed receipt with issued tokens.

API

See inline documentation in the source code for detailed API information.

Examples

See the examples directory for complete usage examples.

License

MIT License. See LICENSE for details.