SDKs Docs

README.md

@@ -44,6 +44,25 @@ enough to send millions of daily emails.
 
 <!-- - **Dedicated IPs**: Support for dedicated IPs users. (coming soon) -->
 
+## SDK
+
+The following SDKs are available or planned:
+
+| Language / Framework | Repository                                                    | Status |
+|----------------------|---------------------------------------------------------------|--------|
+| JavaScript*          | [hyvor/relay-js](https://github.com/hyvor/relay-js)           | WIP    |
+| PHP                  | [hyvor/relay-php](https://github.com/hyvor/relay-php)         | N/A    |
+| └── Symfony (Mailer) | [hyvor/relay-symfony](https://github.com/hyvor/relay-symfony) | N/A    |
+| └── Laravel          | [hyvor/relay-laravel](https://github.com/hyvor/relay-laravel) | N/A    |
+| Go                   | [hyvor/relay-go](https://github.com/hyvor/relay-go)           | N/A    |
+| Ruby                 | [hyvor/relay-ruby](https://github.com/hyvor/relay-ruby)       | N/A    |
+| Python               | [hyvor/relay-python](https://github.com/hyvor/relay-python)   | N/A    |
+| Rust                 | [hyvor/relay-rust](https://github.com/hyvor/relay-rust)       | N/A    |
+| Java                 | [hyvor/relay-java](https://github.com/hyvor/relay-java)       | N/A    |
+| Dotnet               | [hyvor/relay-dotnet](https://github.com/hyvor/relay-dotnet)   | N/A    |
+
+*JavaScript SDK is the primary implementation that other SDKs follow. See [sdk.md](./meta/playbooks/sdk.md) for rules for creating an official library.
+
 ## Screenshots
 
 The sudo dashboard for admins:

SDK.md

@@ -0,0 +1,43 @@
+> [!WARNING]
+> Our SDKS only support email sending at the moment. Other API endpoints, such as domain management, are not planned to be supported in the near term.
+
+This document is the main playbook for SDKs. The Javascript library is the primary implementation. Any updates to this document must be first implemented in the Javascript library.
+
+## 1. RelayClient
+
+Users would initiate the `RelayClient` as the entrypoint:
+
+```ts
+import { RelayClient } from '@hyvor/relay';
+
+const client = new RelayClient({
+
+    // Hyvor Relay Console API key
+    apiKey: '',
+
+    // which Hyvor Relay instance to call
+    // the default must be the cloud URL as shown here
+    baseUrl: 'https://relay.hyvor.com',
+
+    // ===== TIMEOUT ======
+
+    // How long to wait (in milliseconds) when establishing a connection (default 5s)
+    connectionTimeoutMs: 5000,
+    // How long to wait (in milliseconds) for a response before aborting a request (default 30s)
+    requestTimeoutMs: 30000,
+
+    // ===== RETRYING =====
+
+    // Total retry attempts (1 initial + 2 retries)
+    // <= 1 to disable retries
+    retryMaxAttempts: 3,
+    // Wait time before the first retry (default 1s)
+    retryInitialDelayMs: 1000,
+    // Cap the wait time to keep the UX snappy
+    retryMaxDelayMs: 10000,
+    // Exponential factor (delay = initialDelay * factor ^ attempt)
+    retryBackoffFactor: 2
+
+})
+```
+

meta/playbooks/sdk.md

@@ -0,0 +1,18 @@
+Rules for developing a SDK:
+
+- The SDK must be based on the Javascript SDK.
+  - all the features supported by the JS SDK must be supported
+  - configs should match as much as possible with the JS SDK
+- At this moment, only email sending (POST /sends) is supported via the SDKs. Other endpoints, such as creating a domain, is not supported.
+- Use typed DTOs
+  - use Address objects instead of string addresses
+  - if the language supports it, use enums
+- Return/throw custom errors (ValidationFailedError, ServerError, RateLimits)
+- The SDK must be MIT-licensed.
+- The SDK must use semantic versioning.
+- The SDK must be published to the language's most prominent repository
+  - Github Releases must initiate publishing automatically via Github actions
+- Allow injecting a logger and HTTP client for testing, mocking, and debugging.
+- In API requests, the `User-Agent` header must be set to `hyvor/relay-{language}/{version}` (ex: `hyvor/relay-php/1.0.0`)
+- The SDK must have a README with a minimal example for sending an email.
+- The SDK must have 100% code coverage, with Github Actions based CI.