Cơ sở kiến thức

SDK có kiểu

TypeScript trước, rồi mới tới phần còn lại.

Chi tiết

Đã phát hành trên npm và đang được dùng. @openemail/sdk là một client TypeScript hoàn chỉnh, không phụ thuộc gói nào, phát hành ở cả dạng ESM lẫn CommonJS, với một phương thức cho mỗi thao tác có tài liệu mà API phục vụ, cộng thêm hai endpoint meta không cần xác thực mà một bộ sinh client cần tới, khóa được đọc từ OPENEMAIL_API_KEY, thời gian chờ 30 giây cho mỗi lần thử, hai lần thử lại, một tham số apiKey ghi đè theo từng lệnh gọi dành cho tiến trình phục vụ nhiều không gian làm việc, và emails.iterate() để duyệt qua từng trang của một danh sách mà không phải tự viết vòng lặp con trỏ. Nó chạy trên Node 18 trở lên, Workers, Deno, Bun và trình duyệt. Một khóa sai tiền tố sẽ ném lỗi ngay lúc khởi tạo thay vì trả 401 ở lệnh gọi đầu tiên; phép kiểm tra chỉ là tiền tố chứ không hơn, nên một khóa đúng định dạng nhưng đã bị thu hồi vẫn thất bại khi gửi lên mạng.
Nó được giữ khớp với máy chủ bằng một phép kiểm tra tương đương, đọc tài liệu OpenAPI ở mỗi lần build và thất bại nếu hai bên lệch nhau: một phương thức trỏ tới một thao tác mà đặc tả không có, một thao tác có tài liệu nhưng không có phương thức, một danh sách scope không khớp với danh sách mà thao tác đó đòi hỏi, một namespace có phương thức nhưng không có mục nào trong tài liệu tham chiếu, hoặc một phương thức không gửi đúng yêu cầu mà chính manifest của nó nêu tên. Nó in ra những gì nó đã chứng minh, và hôm nay con số đó là 116 phương thức SDK bao phủ toàn bộ 104 thao tác có tài liệu. Hai script sinh mã đứng bên cạnh nó và từ chối xuất ra một thao tác chưa được phân loại hoặc có chứa dấu gạch ngang dài. Đó là lý do client này không phải một lớp bọc được viết sau khi mọi chuyện đã xong. Nó không thể tụt sau API một bản phát hành.
Thứ còn thiếu là hạ tầng phát hành. Gói đã có trên npm, nên bun add @openemail/sdk chạy được, nhưng không có quy trình phát hành tự động: việc phát hành là chạy tay bước kiểm tra trước, bước build và bun publish, tức là một phiên bản lên tới npm khi có người nhớ ra chứ không phải khi thay đổi được hợp nhất. API mà nó mặc định trỏ tới đang bật và đang phản hồi.
TypeScript là ngôn ngữ duy nhất, và tài liệu OpenAPI mới là câu trả lời có chủ ý cho phần còn lại, thay vì năm client viết tay tụt hậu với những tốc độ khác nhau. Trong kho mã không có client Python, Go hay Ruby, và sẽ không có cho tới khi tài liệu đó chính là thứ chúng được sinh ra từ đó.