@nile-squad/nylonpay-ts 1.0.3 → 1.0.5

package/dist/index.d.ts

@@ -273,6 +273,12 @@ type NylonPayConfig = {
     maxPollIntervalMs?: number;
     maxPollDurationMs?: number;
     maxPollAttempts?: number;
+    /**
+     * Receive status updates over an SSE stream (default `true`), falling back to
+     * polling automatically when the stream is unavailable. Set `false` to poll
+     * only.
+     */
+    streaming?: boolean;
     fetch?: typeof globalThis.fetch;
     /** Force a new instance even if one already exists for this key+url pair. */
     force?: boolean;
@@ -280,16 +286,31 @@ type NylonPayConfig = {
     hooks?: SdkHooks;
 };
 /**
- * Structured error returned by SDK operations. `code` is machine-readable
+ * Well-known failure categories. The SDK derives these from the server's
+ * tagged error (or from the transport for `network`/`timeout`) so merchants can
+ * branch on a stable category instead of parsing messages or HTTP status codes.
+ *
+ * - `auth` — invalid/missing/revoked/expired key, bad signature, replay, scope.
+ * - `validation` — input the server rejected.
+ * - `limit` — account/KYC transaction limits exceeded.
+ * - `rate_limit` — too many requests.
+ * - `account` — merchant account missing or not active.
+ * - `provider` — payment provider/engine rejected the operation.
+ * - `not_found` — referenced transaction does not exist.
+ * - `internal` — unexpected server-side failure.
+ * - `network` — request never reached the server (DNS, TLS, connection).
+ * - `timeout` — request exceeded the configured timeout.
+ */
+type SdkErrorCategory = "auth" | "validation" | "limit" | "rate_limit" | "account" | "provider" | "not_found" | "internal" | "network" | "timeout";
+/**
+ * Structured error returned by SDK operations. `category` is machine-readable
  * for branching logic; `message` is human-readable for logs and alerts.
  * `retryable` tells the merchant whether the same request may succeed
  * on re-invocation.
- * @internal
  */
 type SdkError = {
-    code: string;
+    category: SdkErrorCategory;
     message: string;
-    statusCode?: number;
     retryable?: boolean;
 };
 /**
@@ -503,8 +524,8 @@ interface NylonPaySdk {
 interface PaymentInstance {
     /** The transaction reference. Immutable after creation. */
     readonly reference: string;
-    /** Current transaction status. `null` until the first poll resolves. */
-    readonly status: TransactionStatus | null;
+    /** Current transaction status, set from the initiation response and updated on each status change. */
+    readonly status: TransactionStatus;
     /**
      * Register a handler for a payment event. Fires every time the event
      * occurs. Returns the instance for chaining.
@@ -535,20 +556,20 @@ interface PaymentInstance {
     off(event: PaymentEvent, handler: PaymentEventHandler): PaymentInstance;
     /**
      * Block until the transaction reaches a terminal state. Resolves with
-     * the full {@link Transaction} on success. Rejects on failure,
-     * cancellation, or polling error.
+     * the full {@link Transaction} on success, or `null` on failure,
+     * cancellation, or polling error. Never rejects.
      *
      * @example
      * ```ts
-     * try {
-     *   const tx = await payment.wait();
+     * const tx = await payment.wait();
+     * if (tx) {
      *   console.log("Paid:", tx.amount, tx.currency);
-     * } catch (err) {
-     *   console.error("Payment did not succeed:", err.message);
+     * } else {
+     *   console.error("Payment did not succeed");
      * }
      * ```
      */
-    wait(): Promise<Transaction>;
+    wait(): Promise<Transaction | null>;
 }
 
 /**
@@ -593,15 +614,24 @@ declare function createNylonPay(config: NylonPayConfig): NylonPaySdk;
  */
 
 /**
- * Parse an error string into an SdkError object.
- * Tries JSON.parse first; falls back to a generic UNKNOWN error.
+ * Convert a structured SdkError into a throwable Error that still carries the
+ * category and retryable flag. Used by async operations that throw on
+ * initiation failure (invalid key, etc.) so merchants can `catch (e)` and read
+ * `e.category`.
+ */
+declare function createSdkError(error: SdkError): Error & SdkError;
+/**
+ * Parse an error string into a structured SdkError with a `category`.
+ * Tries the JSON envelope first; otherwise pulls the server's
+ * ` -- error-type: <category>` suffix off a raw message, falling back to
+ * category `internal` when untagged.
  *
  * @example
  * ```ts
  * const result = await sdk.getStatus({ reference: "ORDER-123" });
  * if (!result.isOk) {
  *   const error = parseError(result.error);
- *   console.log(error.code, error.message);
+ *   console.log(error.category, error.message);
  * }
  * ```
  */
@@ -624,4 +654,4 @@ declare function parseError(error: string): SdkError;
  */
 declare function verifyWebhookSignature(input: VerifyWebhookInput): boolean;
 
-export { type AfterCollectHook, type AfterPayoutHook, type BankDetails, type BeforeCollectHook, type BeforePayoutHook, type CollectPaymentInput, type CreateInvoiceInput, type Currency, type Customer, type Destination, type EventData, type GetStatusInput, type GetTransactionInput, type InvoiceItem, type InvoiceResponse, type MakePayoutInput, type NylonPayConfig, type NylonPaySdk, type PaymentEvent, type PaymentEventHandler, type PaymentInstance, type PaymentMethod, type PhoneVerification, type SdkError, type SdkHooks, type StatusResponse, type Transaction, type TransactionMode, type TransactionStatus, type TransactionType, type VerifyPhoneInput, type VerifyWebhookInput, type WebhookEventType, type WebhookPayload, createNylonPay, parseError, verifyWebhookSignature };
+export { type AfterCollectHook, type AfterPayoutHook, type BankDetails, type BeforeCollectHook, type BeforePayoutHook, type CollectPaymentInput, type CreateInvoiceInput, type Currency, type Customer, type Destination, type EventData, type GetStatusInput, type GetTransactionInput, type InvoiceItem, type InvoiceResponse, type MakePayoutInput, type NylonPayConfig, type NylonPaySdk, type PaymentEvent, type PaymentEventHandler, type PaymentInstance, type PaymentMethod, type PhoneVerification, type SdkError, type SdkErrorCategory, type SdkHooks, type StatusResponse, type Transaction, type TransactionMode, type TransactionStatus, type TransactionType, type VerifyPhoneInput, type VerifyWebhookInput, type WebhookEventType, type WebhookPayload, createNylonPay, createSdkError, parseError, verifyWebhookSignature };