@moneymq/sdk 0.9.2 → 0.9.4

package/dist/index.d.mts

@@ -430,6 +430,76 @@ declare class ChannelError extends Error {
     code: string;
     constructor(message: string, code: string);
 }
+/**
+ * Event message from the stream
+ */
+interface EventStreamMessage<T = unknown> {
+    type: 'event';
+    event: ChannelEvent<T>;
+}
+/**
+ * Connection state change message
+ */
+interface StateStreamMessage {
+    type: 'state';
+    state: ConnectionState;
+}
+/**
+ * Error message from the stream
+ */
+interface ErrorStreamMessage {
+    type: 'error';
+    error: ChannelError;
+}
+/**
+ * Transaction with actor factory method and convenience methods
+ */
+interface TransactionWithActor extends Transaction {
+    /** Create an actor scoped to this transaction's channel */
+    actor(options?: Omit<ActorOptions, 'secret'>): EventActor;
+    /**
+     * Stream events for this transaction
+     *
+     * Creates an actor internally and yields events from the transaction's channel.
+     */
+    events(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<ChannelEvent>;
+    /**
+     * Attach data to this transaction's channel
+     *
+     * Creates an actor internally if not already created.
+     * The server will create a signed receipt JWT and emit a transaction:completed event.
+     */
+    attach<T = unknown>(data: T): Promise<ChannelEvent<T>>;
+}
+/**
+ * Transaction message (for receivers)
+ * Note: The transaction has an actor() method to create a scoped EventActor
+ */
+interface TransactionStreamMessage {
+    type: 'transaction';
+    transaction: TransactionWithActor;
+}
+/**
+ * Union of all channel stream message types
+ */
+type ChannelStreamMessage<T = unknown> = EventStreamMessage<T> | StateStreamMessage | ErrorStreamMessage;
+/**
+ * Union of all receiver stream message types
+ */
+type ReceiverStreamMessage = TransactionStreamMessage | StateStreamMessage | ErrorStreamMessage;
+/**
+ * Options for the stream() method
+ */
+interface StreamOptions {
+    /** AbortSignal to cancel the stream */
+    signal?: AbortSignal;
+    /** Include state change messages (default: true) */
+    includeState?: boolean;
+    /** Include error messages (default: true) */
+    includeErrors?: boolean;
+}
 /**
  * Base class for channel connections (shared by Reader and Actor)
  */
@@ -480,6 +550,47 @@ declare abstract class BaseChannel {
      * Disconnect from the channel
      */
     disconnect(): void;
+    /**
+     * Stream events as an async iterable
+     *
+     * Automatically connects and yields messages until disconnected or aborted.
+     *
+     * @example
+     * ```typescript
+     * const reader = moneymq.payment.listener('tx-123');
+     *
+     * for await (const message of reader.stream()) {
+     *   if (message.type === 'event') {
+     *     console.log('Event:', message.event.type, message.event.data);
+     *   } else if (message.type === 'state') {
+     *     console.log('State:', message.state);
+     *   } else if (message.type === 'error') {
+     *     console.error('Error:', message.error);
+     *   }
+     * }
+     * ```
+     */
+    stream<T = unknown>(options?: StreamOptions): AsyncGenerator<ChannelStreamMessage<T>>;
+    /**
+     * Stream events directly as an async iterable
+     *
+     * Simpler API that only yields events, ignoring state/error messages.
+     * Automatically connects and yields until disconnected or aborted.
+     *
+     * @example
+     * ```typescript
+     * const listener = moneymq.payment.listener('tx-123');
+     *
+     * for await (const event of listener.events()) {
+     *   if (event.type === 'payment:settled') {
+     *     console.log('Payment settled:', event.data.amount);
+     *   }
+     * }
+     * ```
+     */
+    events<T = unknown>(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<ChannelEvent<T>>;
     protected abstract buildUrl(): string;
     protected handleMessage(event: MessageEvent): void;
     protected setState(state: ConnectionState): void;
@@ -555,7 +666,7 @@ declare class EventActor extends BaseChannel {
 /**
  * Transaction wrapper for receiver callbacks
  */
-declare class TransactionContext implements Transaction {
+declare class TransactionContext implements TransactionWithActor {
     id: string;
     channelId: string;
     basket: BasketItem$1[];
@@ -563,7 +674,12 @@ declare class TransactionContext implements Transaction {
     metadata?: Record<string, unknown>;
     private endpoint;
     private secret;
+    private _actor;
     constructor(data: Transaction, endpoint: string, secret: string);
+    /**
+     * Get or create the internal actor (lazy initialization)
+     */
+    private getOrCreateActor;
     /**
      * Get the payment amount as string (from payment details)
      */
@@ -592,8 +708,39 @@ declare class TransactionContext implements Transaction {
      * Create an actor scoped to this transaction's channel
      *
      * The actor is automatically connected.
+     * Note: If you use events() or send() methods, they share the same internal actor.
      */
     actor(options?: Omit<ActorOptions, 'secret'>): EventActor;
+    /**
+     * Stream events for this transaction
+     *
+     * Creates an actor internally and yields events from the transaction's channel.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of tx.events()) {
+     *   if (event.type === 'payment:settled') {
+     *     await tx.send('order:completed', { orderId: tx.id });
+     *     break;
+     *   }
+     * }
+     * ```
+     */
+    events(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<ChannelEvent>;
+    /**
+     * Attach data to this transaction's channel
+     *
+     * Creates an actor internally if not already created.
+     * The server will create a signed receipt JWT and emit a transaction:completed event.
+     *
+     * @example
+     * ```typescript
+     * await tx.attach({ orderId: tx.id, trackingNumber: '...' });
+     * ```
+     */
+    attach<T = unknown>(data: T): Promise<ChannelEvent<T>>;
 }
 /**
  * Transaction handler callback
@@ -666,6 +813,57 @@ declare class EventReceiver {
      * Disconnect from the transaction stream
      */
     disconnect(): void;
+    /**
+     * Stream transactions as an async iterable
+     *
+     * Automatically connects and yields messages until disconnected or aborted.
+     *
+     * @example
+     * ```typescript
+     * const receiver = moneymq.payment.processor();
+     *
+     * for await (const message of receiver.stream()) {
+     *   if (message.type === 'transaction') {
+     *     const tx = message.transaction;
+     *     console.log('New transaction:', tx.id);
+     *
+     *     const actor = tx.actor();
+     *     // Handle the transaction...
+     *   } else if (message.type === 'state') {
+     *     console.log('State:', message.state);
+     *   } else if (message.type === 'error') {
+     *     console.error('Error:', message.error);
+     *   }
+     * }
+     * ```
+     */
+    stream(options?: StreamOptions): AsyncGenerator<ReceiverStreamMessage>;
+    /**
+     * Stream transactions directly as an async iterable
+     *
+     * Simpler API that only yields transactions, ignoring state/error messages.
+     * Automatically connects and yields until disconnected or aborted.
+     *
+     * @example
+     * ```typescript
+     * const processor = moneymq.payment.processor();
+     *
+     * for await (const tx of processor.transactions()) {
+     *   console.log('New transaction:', tx.id, tx.payment?.amount);
+     *
+     *   const actor = tx.actor();
+     *   for await (const event of actor.events()) {
+     *     if (event.type === 'payment:settled') {
+     *       await actor.send('order:completed', { orderId: tx.id });
+     *       break;
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    transactions(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<TransactionWithActor>;
     private setState;
     private shouldReconnect;
     private scheduleReconnect;
@@ -1887,4 +2085,4 @@ declare class CheckoutReceipt {
     };
 }
 
-export { type ActorOptions, type Attachments, type BasketItem, ChannelError, type ChannelErrorHandler, type ChannelEvent, type ChannelEventHandler, type CheckoutCreateParams, type CheckoutLineItem, CheckoutReceipt, type CheckoutSession, type CloudEventEnvelope, type ConnectionHandler, type ConnectionState, type Customer, type CustomerCreateParams, type CustomerUpdateParams, type ErrorHandler, EventActor, type EventHandler, EventReader, EventReceiver, EventStream, type EventStreamOptions, type EventStreamState, type ExperimentConfig, type GetSignerParams, MoneyMQ, type MoneyMQConfig, type MoneyMQEventMap, type MoneyMQEventType, type PayParams, type PayResult, type Payment, type PaymentDetails, type PaymentEvent, type PaymentFlow, type PaymentIntent, type PaymentIntentCreateParams, type PaymentLink, type PaymentLinkCreateParams, type PaymentListParams, PaymentRequiredError, type PaymentRequirements, type PaymentSettlementEvent, type PaymentSettlementFailedData, type PaymentSettlementSucceededData, type PaymentVerificationEvent, type PaymentVerificationFailedData, type PaymentVerificationSucceededData, type Payout, type PayoutCreateParams, type PayoutListParams, type PayoutSettings, type PayoutSettingsUpdateParams, type Price, type PriceCreateParams, type PriceRecurring, type ProcessorData, type Product, type ProductAccessParams, type ProductAccessResponse, type ProductCreateParams, type ProductFeature$1 as ProductFeature, type ProductListParams, type ProductPrice, type ReaderOptions, type ReceiptClaims, type ReceiverOptions, type ServerConfig, type StateHandler, type Transaction, type TransactionHandler, type X402ClientConfig, buildEventStreamUrl, computeChannelId, createEventActor, createEventReader, createEventReceiver, createEventStream, fetchConfig, getRpcUrl, isPaymentSettlementFailed, isPaymentSettlementSucceeded, isPaymentVerificationFailed, isPaymentVerificationSucceeded, parseCloudEvent };
+export { type ActorOptions, type Attachments, type BasketItem, ChannelError, type ChannelErrorHandler, type ChannelEvent, type ChannelEventHandler, type ChannelStreamMessage, type CheckoutCreateParams, type CheckoutLineItem, CheckoutReceipt, type CheckoutSession, type CloudEventEnvelope, type ConnectionHandler, type ConnectionState, type Customer, type CustomerCreateParams, type CustomerUpdateParams, type ErrorHandler, type ErrorStreamMessage, EventActor, type EventHandler, EventReader, EventReceiver, EventStream, type EventStreamMessage, type EventStreamOptions, type EventStreamState, type ExperimentConfig, type GetSignerParams, MoneyMQ, type MoneyMQConfig, type MoneyMQEventMap, type MoneyMQEventType, type PayParams, type PayResult, type Payment, type PaymentDetails, type PaymentEvent, type PaymentFlow, type PaymentIntent, type PaymentIntentCreateParams, type PaymentLink, type PaymentLinkCreateParams, type PaymentListParams, PaymentRequiredError, type PaymentRequirements, type PaymentSettlementEvent, type PaymentSettlementFailedData, type PaymentSettlementSucceededData, type PaymentVerificationEvent, type PaymentVerificationFailedData, type PaymentVerificationSucceededData, type Payout, type PayoutCreateParams, type PayoutListParams, type PayoutSettings, type PayoutSettingsUpdateParams, type Price, type PriceCreateParams, type PriceRecurring, type ProcessorData, type Product, type ProductAccessParams, type ProductAccessResponse, type ProductCreateParams, type ProductFeature$1 as ProductFeature, type ProductListParams, type ProductPrice, type ReaderOptions, type ReceiptClaims, type ReceiverOptions, type ReceiverStreamMessage, type ServerConfig, type StateHandler, type StateStreamMessage, type StreamOptions, type Transaction, type TransactionHandler, type TransactionStreamMessage, type TransactionWithActor, type X402ClientConfig, buildEventStreamUrl, computeChannelId, createEventActor, createEventReader, createEventReceiver, createEventStream, fetchConfig, getRpcUrl, isPaymentSettlementFailed, isPaymentSettlementSucceeded, isPaymentVerificationFailed, isPaymentVerificationSucceeded, parseCloudEvent };

package/dist/index.d.ts

@@ -430,6 +430,76 @@ declare class ChannelError extends Error {
     code: string;
     constructor(message: string, code: string);
 }
+/**
+ * Event message from the stream
+ */
+interface EventStreamMessage<T = unknown> {
+    type: 'event';
+    event: ChannelEvent<T>;
+}
+/**
+ * Connection state change message
+ */
+interface StateStreamMessage {
+    type: 'state';
+    state: ConnectionState;
+}
+/**
+ * Error message from the stream
+ */
+interface ErrorStreamMessage {
+    type: 'error';
+    error: ChannelError;
+}
+/**
+ * Transaction with actor factory method and convenience methods
+ */
+interface TransactionWithActor extends Transaction {
+    /** Create an actor scoped to this transaction's channel */
+    actor(options?: Omit<ActorOptions, 'secret'>): EventActor;
+    /**
+     * Stream events for this transaction
+     *
+     * Creates an actor internally and yields events from the transaction's channel.
+     */
+    events(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<ChannelEvent>;
+    /**
+     * Attach data to this transaction's channel
+     *
+     * Creates an actor internally if not already created.
+     * The server will create a signed receipt JWT and emit a transaction:completed event.
+     */
+    attach<T = unknown>(data: T): Promise<ChannelEvent<T>>;
+}
+/**
+ * Transaction message (for receivers)
+ * Note: The transaction has an actor() method to create a scoped EventActor
+ */
+interface TransactionStreamMessage {
+    type: 'transaction';
+    transaction: TransactionWithActor;
+}
+/**
+ * Union of all channel stream message types
+ */
+type ChannelStreamMessage<T = unknown> = EventStreamMessage<T> | StateStreamMessage | ErrorStreamMessage;
+/**
+ * Union of all receiver stream message types
+ */
+type ReceiverStreamMessage = TransactionStreamMessage | StateStreamMessage | ErrorStreamMessage;
+/**
+ * Options for the stream() method
+ */
+interface StreamOptions {
+    /** AbortSignal to cancel the stream */
+    signal?: AbortSignal;
+    /** Include state change messages (default: true) */
+    includeState?: boolean;
+    /** Include error messages (default: true) */
+    includeErrors?: boolean;
+}
 /**
  * Base class for channel connections (shared by Reader and Actor)
  */
@@ -480,6 +550,47 @@ declare abstract class BaseChannel {
      * Disconnect from the channel
      */
     disconnect(): void;
+    /**
+     * Stream events as an async iterable
+     *
+     * Automatically connects and yields messages until disconnected or aborted.
+     *
+     * @example
+     * ```typescript
+     * const reader = moneymq.payment.listener('tx-123');
+     *
+     * for await (const message of reader.stream()) {
+     *   if (message.type === 'event') {
+     *     console.log('Event:', message.event.type, message.event.data);
+     *   } else if (message.type === 'state') {
+     *     console.log('State:', message.state);
+     *   } else if (message.type === 'error') {
+     *     console.error('Error:', message.error);
+     *   }
+     * }
+     * ```
+     */
+    stream<T = unknown>(options?: StreamOptions): AsyncGenerator<ChannelStreamMessage<T>>;
+    /**
+     * Stream events directly as an async iterable
+     *
+     * Simpler API that only yields events, ignoring state/error messages.
+     * Automatically connects and yields until disconnected or aborted.
+     *
+     * @example
+     * ```typescript
+     * const listener = moneymq.payment.listener('tx-123');
+     *
+     * for await (const event of listener.events()) {
+     *   if (event.type === 'payment:settled') {
+     *     console.log('Payment settled:', event.data.amount);
+     *   }
+     * }
+     * ```
+     */
+    events<T = unknown>(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<ChannelEvent<T>>;
     protected abstract buildUrl(): string;
     protected handleMessage(event: MessageEvent): void;
     protected setState(state: ConnectionState): void;
@@ -555,7 +666,7 @@ declare class EventActor extends BaseChannel {
 /**
  * Transaction wrapper for receiver callbacks
  */
-declare class TransactionContext implements Transaction {
+declare class TransactionContext implements TransactionWithActor {
     id: string;
     channelId: string;
     basket: BasketItem$1[];
@@ -563,7 +674,12 @@ declare class TransactionContext implements Transaction {
     metadata?: Record<string, unknown>;
     private endpoint;
     private secret;
+    private _actor;
     constructor(data: Transaction, endpoint: string, secret: string);
+    /**
+     * Get or create the internal actor (lazy initialization)
+     */
+    private getOrCreateActor;
     /**
      * Get the payment amount as string (from payment details)
      */
@@ -592,8 +708,39 @@ declare class TransactionContext implements Transaction {
      * Create an actor scoped to this transaction's channel
      *
      * The actor is automatically connected.
+     * Note: If you use events() or send() methods, they share the same internal actor.
      */
     actor(options?: Omit<ActorOptions, 'secret'>): EventActor;
+    /**
+     * Stream events for this transaction
+     *
+     * Creates an actor internally and yields events from the transaction's channel.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of tx.events()) {
+     *   if (event.type === 'payment:settled') {
+     *     await tx.send('order:completed', { orderId: tx.id });
+     *     break;
+     *   }
+     * }
+     * ```
+     */
+    events(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<ChannelEvent>;
+    /**
+     * Attach data to this transaction's channel
+     *
+     * Creates an actor internally if not already created.
+     * The server will create a signed receipt JWT and emit a transaction:completed event.
+     *
+     * @example
+     * ```typescript
+     * await tx.attach({ orderId: tx.id, trackingNumber: '...' });
+     * ```
+     */
+    attach<T = unknown>(data: T): Promise<ChannelEvent<T>>;
 }
 /**
  * Transaction handler callback
@@ -666,6 +813,57 @@ declare class EventReceiver {
      * Disconnect from the transaction stream
      */
     disconnect(): void;
+    /**
+     * Stream transactions as an async iterable
+     *
+     * Automatically connects and yields messages until disconnected or aborted.
+     *
+     * @example
+     * ```typescript
+     * const receiver = moneymq.payment.processor();
+     *
+     * for await (const message of receiver.stream()) {
+     *   if (message.type === 'transaction') {
+     *     const tx = message.transaction;
+     *     console.log('New transaction:', tx.id);
+     *
+     *     const actor = tx.actor();
+     *     // Handle the transaction...
+     *   } else if (message.type === 'state') {
+     *     console.log('State:', message.state);
+     *   } else if (message.type === 'error') {
+     *     console.error('Error:', message.error);
+     *   }
+     * }
+     * ```
+     */
+    stream(options?: StreamOptions): AsyncGenerator<ReceiverStreamMessage>;
+    /**
+     * Stream transactions directly as an async iterable
+     *
+     * Simpler API that only yields transactions, ignoring state/error messages.
+     * Automatically connects and yields until disconnected or aborted.
+     *
+     * @example
+     * ```typescript
+     * const processor = moneymq.payment.processor();
+     *
+     * for await (const tx of processor.transactions()) {
+     *   console.log('New transaction:', tx.id, tx.payment?.amount);
+     *
+     *   const actor = tx.actor();
+     *   for await (const event of actor.events()) {
+     *     if (event.type === 'payment:settled') {
+     *       await actor.send('order:completed', { orderId: tx.id });
+     *       break;
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    transactions(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<TransactionWithActor>;
     private setState;
     private shouldReconnect;
     private scheduleReconnect;
@@ -1887,4 +2085,4 @@ declare class CheckoutReceipt {
     };
 }
 
-export { type ActorOptions, type Attachments, type BasketItem, ChannelError, type ChannelErrorHandler, type ChannelEvent, type ChannelEventHandler, type CheckoutCreateParams, type CheckoutLineItem, CheckoutReceipt, type CheckoutSession, type CloudEventEnvelope, type ConnectionHandler, type ConnectionState, type Customer, type CustomerCreateParams, type CustomerUpdateParams, type ErrorHandler, EventActor, type EventHandler, EventReader, EventReceiver, EventStream, type EventStreamOptions, type EventStreamState, type ExperimentConfig, type GetSignerParams, MoneyMQ, type MoneyMQConfig, type MoneyMQEventMap, type MoneyMQEventType, type PayParams, type PayResult, type Payment, type PaymentDetails, type PaymentEvent, type PaymentFlow, type PaymentIntent, type PaymentIntentCreateParams, type PaymentLink, type PaymentLinkCreateParams, type PaymentListParams, PaymentRequiredError, type PaymentRequirements, type PaymentSettlementEvent, type PaymentSettlementFailedData, type PaymentSettlementSucceededData, type PaymentVerificationEvent, type PaymentVerificationFailedData, type PaymentVerificationSucceededData, type Payout, type PayoutCreateParams, type PayoutListParams, type PayoutSettings, type PayoutSettingsUpdateParams, type Price, type PriceCreateParams, type PriceRecurring, type ProcessorData, type Product, type ProductAccessParams, type ProductAccessResponse, type ProductCreateParams, type ProductFeature$1 as ProductFeature, type ProductListParams, type ProductPrice, type ReaderOptions, type ReceiptClaims, type ReceiverOptions, type ServerConfig, type StateHandler, type Transaction, type TransactionHandler, type X402ClientConfig, buildEventStreamUrl, computeChannelId, createEventActor, createEventReader, createEventReceiver, createEventStream, fetchConfig, getRpcUrl, isPaymentSettlementFailed, isPaymentSettlementSucceeded, isPaymentVerificationFailed, isPaymentVerificationSucceeded, parseCloudEvent };
+export { type ActorOptions, type Attachments, type BasketItem, ChannelError, type ChannelErrorHandler, type ChannelEvent, type ChannelEventHandler, type ChannelStreamMessage, type CheckoutCreateParams, type CheckoutLineItem, CheckoutReceipt, type CheckoutSession, type CloudEventEnvelope, type ConnectionHandler, type ConnectionState, type Customer, type CustomerCreateParams, type CustomerUpdateParams, type ErrorHandler, type ErrorStreamMessage, EventActor, type EventHandler, EventReader, EventReceiver, EventStream, type EventStreamMessage, type EventStreamOptions, type EventStreamState, type ExperimentConfig, type GetSignerParams, MoneyMQ, type MoneyMQConfig, type MoneyMQEventMap, type MoneyMQEventType, type PayParams, type PayResult, type Payment, type PaymentDetails, type PaymentEvent, type PaymentFlow, type PaymentIntent, type PaymentIntentCreateParams, type PaymentLink, type PaymentLinkCreateParams, type PaymentListParams, PaymentRequiredError, type PaymentRequirements, type PaymentSettlementEvent, type PaymentSettlementFailedData, type PaymentSettlementSucceededData, type PaymentVerificationEvent, type PaymentVerificationFailedData, type PaymentVerificationSucceededData, type Payout, type PayoutCreateParams, type PayoutListParams, type PayoutSettings, type PayoutSettingsUpdateParams, type Price, type PriceCreateParams, type PriceRecurring, type ProcessorData, type Product, type ProductAccessParams, type ProductAccessResponse, type ProductCreateParams, type ProductFeature$1 as ProductFeature, type ProductListParams, type ProductPrice, type ReaderOptions, type ReceiptClaims, type ReceiverOptions, type ReceiverStreamMessage, type ServerConfig, type StateHandler, type StateStreamMessage, type StreamOptions, type Transaction, type TransactionHandler, type TransactionStreamMessage, type TransactionWithActor, type X402ClientConfig, buildEventStreamUrl, computeChannelId, createEventActor, createEventReader, createEventReceiver, createEventStream, fetchConfig, getRpcUrl, isPaymentSettlementFailed, isPaymentSettlementSucceeded, isPaymentVerificationFailed, isPaymentVerificationSucceeded, parseCloudEvent };