@nile-squad/nylonpay-ts 1.0.4 → 1.0.6

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;
 };
 /**
@@ -313,6 +334,17 @@ type EventData = {
     transaction?: Transaction;
     /** Error message. Present for the `"error"` event. */
     error?: string;
+    /**
+     * Machine-readable failure category. Present for the `"error"` event when the
+     * failure carries one (initiation rejection, polling/stream failure) — lets
+     * merchants branch on a stable category instead of parsing the message.
+     */
+    category?: SdkErrorCategory;
+    /**
+     * Whether re-invoking the same operation may succeed. Present for the
+     * `"error"` event when known.
+     */
+    retryable?: boolean;
     /** ISO 8601 timestamp of when the event was emitted. */
     timestamp: string;
 };
@@ -336,8 +368,12 @@ interface NylonPaySdk {
      * Returns a {@link PaymentInstance} that polls for status updates and emits
      * events (`processing`, `success`, `failed`, `cancelled`, `error`).
      *
-     * Auto-generates an idempotency `reference` if omitted. Throws on invalid
-     * input (zero amount, empty phone, bank method without bank details).
+     * Auto-generates an idempotency `reference` if omitted. Throws *synchronously*
+     * only on invalid input (zero amount, empty phone, bank method without bank
+     * details) — programmer errors caught before any network call. A server-side
+     * initiation rejection (auth, limit, provider, network, timeout) does **not**
+     * throw: the returned instance emits an `"error"` event carrying `category`
+     * and `retryable`, and `wait()` resolves `null`.
      *
      * @example
      * ```ts
@@ -350,6 +386,7 @@ interface NylonPaySdk {
      *
      * payment.on("success", ({ transaction }) => fulfillOrder(transaction));
      * payment.on("failed", ({ error }) => notifyCustomer(error));
+     * payment.on("error", ({ error, category }) => log.error(category, error));
      * ```
      */
     collectPayment(input: CollectPaymentInput): Promise<PaymentInstance>;
@@ -377,7 +414,10 @@ interface NylonPaySdk {
      * Returns a {@link PaymentInstance} that polls for status updates and emits
      * events as the payout progresses.
      *
-     * Auto-generates an idempotency `reference` if omitted.
+     * Auto-generates an idempotency `reference` if omitted. Same error semantics
+     * as {@link collectPayment}: throws synchronously on invalid input, but a
+     * server-side initiation rejection surfaces as an `"error"` event (with
+     * `category`/`retryable`) rather than a throw.
      *
      * @example
      * ```ts
@@ -503,8 +543,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.
@@ -593,15 +633,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 +673,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 };