Frequently Asked Questions about ZBD Payments TypeScript SDK

Q: What is the ZBD Payments TypeScript SDK?

A: The ZBD Payments TypeScript SDK (@zbddev/payments-sdk) is a library that provides convenient access to the ZBD Payments REST API from server-side TypeScript or JavaScript. It simplifies the process of integrating Bitcoin Lightning Network payments into your applications.

Q: How do I install the ZBD Payments TypeScript SDK?

A: You can install the SDK using npm with the command: npm install @zbddev/payments-sdk.

Q: What are the requirements for using the ZBD Payments TypeScript SDK?

A: The SDK requires TypeScript >= 4.9 and supports various runtimes including web browsers, Node.js 20 LTS or later, Deno v1.28.0 or higher, Bun 1.0 or later, Cloudflare Workers, and Vercel Edge Runtime.

Q: How do I handle errors when using the ZBD Payments TypeScript SDK?

A: The SDK throws subclasses of APIError for non-success status codes. You can catch these errors to handle specific error scenarios like BadRequestError, AuthenticationError, NotFoundError, etc. The SDK also provides error codes that simplify debugging and ensure application stability.

Q: Does the ZBD Payments TypeScript SDK support automatic retries?

A: Yes, the SDK automatically retries certain errors (e.g., connection errors, rate limits) with an exponential backoff. You can configure or disable this feature using the maxRetries option.

Q: How can I configure timeouts for requests?

A: You can configure the timeout for requests using the timeout option when instantiating the client or making a request. The default timeout is 1 minute.

Q: Can I access the raw Response data (e.g., headers)?

A: Yes, you can access the raw Response object using the .asResponse() or .withResponse() methods on the APIPromise returned by the SDK’s methods.

Q: How do I configure logging with the ZBD Payments TypeScript SDK?

A: You can configure logging using the ZBD_PAYMENTS_LOG environment variable or the logLevel client option. You can also provide a custom logger.

Q: How do I make custom/undocumented requests with the SDK?

A: You can use client.get, client.post, and other HTTP verbs to make requests to undocumented endpoints. For undocumented parameters, you can use // @ts-expect-error on the parameter.

Q: Can I customize the fetch client used by the SDK?

A: Yes, you can either polyfill the global fetch function or pass a custom fetch function to the client.

Q: How can I configure proxies with the ZBD Payments TypeScript SDK?

A: You can configure proxies by providing custom fetchOptions that add runtime-specific proxy options to requests. The implementation depends on the runtime environment (Node, Bun, Deno).

Q: Where can I find the REST API documentation for ZBD Payments?

A: The REST API documentation can be found on zbd.dev.