Skip to content

SDKs

Zorl has two TypeScript packages that are real: @zorl/mail and @zorl/base. Each is a thin wrapper over the HTTP API on the Mail and Base pages, and everything either one does can also be done with curl. Neither is on npm.

@zorl/mail

@zorl/mail sends mail through POST /v1/send. It does not read mail, manage webhooks or make keys; those are in the HTTP API.

How to get it

The package is marked private and is not published, so there is no npm install line for it. In Zorl's own repository it is a workspace package that other apps import by name. The package's own notes say that anything outside that repository copies its src folder. The source is TypeScript that imports its own files without extensions, so it needs a bundler or a build step; Node cannot load it as it is.

Example

import { ZMailSender } from "@zorl/mail"

const sender = new ZMailSender({
  baseUrl: "https://mail.zorl.cloud",
  apiKey: process.env.ZMAIL_API_KEY!, // zm_your_key
})

try {
  const result = await sender.send({
    from: "Your Name <[email protected]>",
    to: "[email protected]",
    subject: "Hello",
    text: "Plain text body",
  })
  console.log(result.id, result.queuedAt, result.messageId)
} catch (e) {
  const err = e as { code: string; message: string; cause?: unknown }
  console.error(err.code, err.message, err.cause)
}

send() returns id, queuedAt and adapter, and when the server gives them messageId, warnings, trace_url and sandbox_url. All of the fields of a message are the ones in the fields table on the Mail page.

Errors

A failed send throws a plain object, not an Error, with code, message and cause, which holds the body the server answered with. The code comes from the status only.

codeWhen
AUTHORIZATIONThe server answered 401 or 403.
RATE_LIMITThe server answered 429.
PROVIDER_DOWNThe server answered 500 or above, or could not be reached.
INVALID_INPUTAny other failure, such as 400. The server's own code is in cause.

The package also exports ConsoleSender, which prints a message instead of sending it, and FailingSender, which always fails, for tests.

@zorl/base

@zorl/base covers the data API and the account calls of the Base and Accounts pages.

How to get it

It is available the same way as @zorl/mail: private, not published, a workspace package in Zorl's repository, and a folder to copy elsewhere.

Example

import { createBaseClient, isPreconditionFailed } from "@zorl/base"

const base = createBaseClient({
  baseUrl: "https://base.zorl.cloud",
  apiKey: process.env.ZBASE_API_KEY!,
})

// Rows: a table of your own (any name the Base page allows), and a key inside it.
const notes = base.data<{ text: string }>("your_table")

const put = await notes.put("note-1", { text: "first" })
console.log("created:", put.created, "etag:", put.etag)

const row = await notes.get("note-1")
console.log("read:", row?.data, row?.updatedAt)

try {
  await notes.put("note-1", { text: "second" }, { ifMatch: "not-the-current-etag" })
} catch (e) {
  if (isPreconditionFailed(e)) console.log("someone else changed it first")
  else throw e
}

await notes.delete("note-1")
console.log("after delete:", await notes.get("note-1"))

// Errors
try {
  await base.data("Not_A_Table").get("x") // capital letters break the naming rule: 400
} catch (e) {
  const err = e as { code: string; status: number; message: string }
  console.log(err.code, err.status, err.message)
}
  • data(table) gives get, put and delete. get returns null for a row that is not there. put takes expiresAt and ifMatch; delete takes ifMatch and hard. It does not send If-None-Match, so a create-only write needs the HTTP call.
  • auth() gives the calls of Signing in from code, and the calls to list, make and revoke keys.

A failed call throws a BaseError with a code (BAD_REQUEST, UNAUTHORIZED, NOT_FOUND, EXPIRED, PAYLOAD_TOO_LARGE, PRECONDITION_FAILED, SERVER_ERROR, NETWORK, MALFORMED_TOKEN, LIMIT_EXCEEDED or UNKNOWN), the HTTP status and the body in cause. A 403 for one of the account's limits becomes LIMIT_EXCEEDED, and isLimitExceeded(err) tells it apart; the limit's code (table_limit, row_limit or storage_limit), the limit and the use are in cause. Any other 403 becomes UNKNOWN.

The other packages

The repository holds three more packages, @zorl/hub, @zorl/deploy and @zorl/ai. None of them is usable: each is a package.json and one file that exports a single constant, and none has a client, a function or a type. Their README files describe what they are meant to become, which is not something you can call today. Zorl Hub and Zorl Deploy are not open to accounts (see Hub and Deploy), and @zorl/ai is listed as coming.