@sendora/sdk 1.2.0 → 2.1.0

package/dist/webhooks.js

@@ -54,6 +54,32 @@ export class WebhooksResource {
             signal: options.signal,
         });
     }
+    /**
+     * Adds a second live secret and answers its value once. Every delivery
+     * then carries one signature per live secret, the newest first, so
+     * switch your receiver to the new secret and delete the old one; a third
+     * is refused with `secret_limit`.
+     *
+     *
+     * const { secret, secretId } = await sendora.webhooks.createSecret(webhookId);
+     */
+    createSecret(webhookId, options = {}) {
+        return this.#transport.request({
+            method: 'POST',
+            path: `/v1/webhooks/${encodeURIComponent(webhookId)}/secrets`,
+            idempotent: false,
+            signal: options.signal,
+        });
+    }
+    /** Deletes a secret; deliveries are no longer signed with it. The last live secret is refused (`last_secret`). */
+    deleteSecret(webhookId, secretId, options = {}) {
+        return this.#transport.request({
+            method: 'DELETE',
+            path: `/v1/webhooks/${encodeURIComponent(webhookId)}/secrets/${encodeURIComponent(secretId)}`,
+            idempotent: true,
+            signal: options.signal,
+        });
+    }
     /**
      * One page of the events handed to the webhook, newest first, with the
      * outcome of the last attempt; `status` narrows to `pending`,

package/dist/webhooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendora/sdk",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "description": "The official TypeScript SDK for Sendora, transactional email delivery.",
   "license": "MIT",
   "type": "module",
@@ -33,10 +33,10 @@
     "typescript": "~6.0.3",
     "vitest": "^4.1.11",
     "zod": "^4.6.2",
-    "@sendora/db": "0.0.0",
-    "@sendora/domain": "0.0.0",
+    "@sendora/observability": "0.0.0",
     "@sendora/api": "0.0.0",
-    "@sendora/observability": "0.0.0"
+    "@sendora/domain": "0.0.0",
+    "@sendora/db": "0.0.0"
   },
   "scripts": {
     "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json"

package/skills/sendora/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sendora
-description: Send transactional email through Sendora with @sendora/sdk, read the message log, manage streams, suppressions, tokens, webhooks and sending domains, and receive signed webhooks. Use when a task mentions Sendora, @sendora/sdk, or sending email from a system hosted in Sweden.
+description: Send transactional email through Sendora with @sendora/sdk, read the message log, manage streams, suppressions, keys, webhooks, servers and sending domains, and receive signed webhooks. Use when a task mentions Sendora, @sendora/sdk, or sending email from a system hosted in Sweden.
 ---
 
 # Sendora
@@ -12,12 +12,20 @@ complete reference; every call, every error code and every event is in it.
 
 ## Rules
 
-- The API token is a secret. Read it from the environment on the server
-  and never send it to a browser. `new Sendora({ token })` throws when the
-  token is missing, so construct the client at startup.
-- One client per server token: `const sendora = new Sendora({ token })`.
-  Every resource hangs off it: `email`, `messages`, `streams`,
-  `suppressions`, `tokens`, `webhooks`, `domains`, `inboundDomains`.
+- Two kinds of key, two clients. A server key (`sk_…`) drives
+  `new Sendora({ token })`: `email`, `messages`, `inbound`, `streams`,
+  `suppressions`, `tokens`, `webhooks`, `inboundDomains`, everything inside
+  one server. An account key (`ak_…`) drives `new SendoraAccount({ token })`:
+  `servers`, `servers.tokens` and `domains`, and it never sends. A key of
+  the wrong kind throws `wrong_token_kind`.
+- Every key is a secret. Read it from the environment on the server and
+  never send it to a browser. Either client throws when its key is
+  missing, so construct it at startup.
+- A server is created with its first key: `account.servers.create({ name })`
+  answers `token.token` once, and `new Sendora({ token })` sends with it. A
+  server or the account holds at most two live keys, so rotate by creating
+  the new key, switching to it, then revoking the old one; the last live
+  key can never be revoked.
 - Every method takes what the route takes and answers what the route
   answers. Do not build request bodies by hand or call `fetch` yourself.
 - Do not add idempotency keys or retry loops of your own. The SDK gives
@@ -40,8 +48,10 @@ complete reference; every call, every error code and every event is in it.
   `suppressions.delete({ address })`; a spam complaint cannot be lifted by
   the customer. Lists are per stream: pass `streamId` when the send went on
   a stream other than the default.
-- `from` must be on a verified sending domain; `domains.create` answers
-  the two DNS records to add, and `domains.verify` checks them now.
+- `from` must be on a verified sending domain of the account;
+  `account.domains.create` answers the two DNS records to add, and
+  `account.domains.verify` checks them now. A server key cannot manage
+  domains.
 - A message goes on the server's default transactional stream unless it
   names another with `streamId`; `streams.create` adds one. Never make a
   stream per message or per customer; a stream is a kind of mail.

package/src/account.ts

@@ -0,0 +1,40 @@
+import { DomainsResource } from './domains.ts';
+import { transportFor, type ClientOptions } from './options.ts';
+import { ServersResource } from './servers.ts';
+
+export interface SendoraAccountOptions extends ClientOptions {
+  /**
+   * An account key (`ak_…`), created by an administrator in the dashboard.
+   * It manages the account and never sends. Keep it on the server; never
+   * ship it to a browser. `undefined`, as an unset environment variable
+   * gives, throws at construction rather than at the first call.
+   */
+  token: string | undefined;
+}
+
+/**
+ * The account client: the servers, each server's keys and the sending
+ * domains, under an account key. Sending, the log, streams, suppressions
+ * and webhooks belong to a server and to `Sendora` with a server key.
+ *
+ * @example
+ * import { Sendora, SendoraAccount } from '@sendora/sdk';
+ *
+ * const account = new SendoraAccount({ token: process.env.SENDORA_ACCOUNT_TOKEN });
+ * const server = await account.servers.create({ name: 'Fakturering' });
+ * const sendora = new Sendora({ token: server.token.token });
+ */
+export class SendoraAccount {
+  readonly servers: ServersResource;
+  readonly domains: DomainsResource;
+
+  constructor(options: SendoraAccountOptions) {
+    const transport = transportFor(
+      options.token,
+      options,
+      'SendoraAccount needs an account key (ak_…); an administrator creates one in the dashboard.',
+    );
+    this.servers = new ServersResource(transport);
+    this.domains = new DomainsResource(transport);
+  }
+}

package/src/client.ts

@@ -1,39 +1,28 @@
-import { DomainsResource } from './domains.ts';
 import { BroadcastsResource } from './broadcasts.ts';
 import { EmailResource } from './email.ts';
 import { InboundResource } from './inbound.ts';
 import { InboundDomainsResource } from './inbound-domains.ts';
 import { MessagesResource } from './messages.ts';
-import { DEFAULT_MAX_RETRIES } from './retry.ts';
+import { transportFor, type ClientOptions } from './options.ts';
 import { StreamsResource } from './streams.ts';
 import { SuppressionsResource } from './suppressions.ts';
 import { TokensResource } from './tokens.ts';
-import { Transport } from './transport.ts';
-import { SDK_VERSION } from './version.ts';
 import { WebhooksResource } from './webhooks.ts';
 
-export const DEFAULT_BASE_URL = 'https://api.sendora.se';
-const DEFAULT_TIMEOUT_MS = 30_000;
-
-export interface SendoraOptions {
+export interface SendoraOptions extends ClientOptions {
   /**
-   * A server's API token, created in the dashboard. Keep it on the server;
-   * never ship it to a browser. `undefined`, as an unset environment
-   * variable gives, throws at construction rather than at the first call.
+   * A server key (`sk_…`), answered once when the server is created or a
+   * key is added to it. Keep it on the server; never ship it to a browser.
+   * `undefined`, as an unset environment variable gives, throws at
+   * construction rather than at the first call.
    */
   token: string | undefined;
-  /** The API's origin; https://api.sendora.se unless you test against another. */
-  baseUrl?: string | undefined;
-  /** The fetch to use; the global one unless you need a proxy or a fake. */
-  fetch?: typeof fetch | undefined;
-  /** How long one attempt may take; 30 seconds by default. */
-  timeoutMs?: number | undefined;
-  /** How many times a failed call is repeated when repeating is safe; 2 by default, 0 turns retries off. */
-  maxRetries?: number | undefined;
 }
 
 /**
- * The client. One instance per server token; every resource hangs off it.
+ * The server client. One instance per server key; every resource of the
+ * server hangs off it. The account's servers and sending domains are
+ * `SendoraAccount` with an account key.
  *
  * @example
  * import { Sendora } from '@sendora/sdk';
@@ -56,30 +45,13 @@ export class Sendora {
   readonly suppressions: SuppressionsResource;
   readonly tokens: TokensResource;
   readonly webhooks: WebhooksResource;
-  readonly domains: DomainsResource;
 
   constructor(options: SendoraOptions) {
-    if (options.token === undefined || options.token.trim() === '') {
-      throw new TypeError('Sendora needs a server API token; create one in the dashboard.');
-    }
-    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
-    new URL(baseUrl);
-    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    if (!(timeoutMs > 0)) {
-      throw new TypeError('timeoutMs must be a positive number of milliseconds.');
-    }
-    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
-    if (!Number.isInteger(maxRetries) || maxRetries < 0) {
-      throw new TypeError('maxRetries must be a whole number of zero or more.');
-    }
-    const transport = new Transport({
-      baseUrl,
-      token: options.token,
-      fetch: options.fetch ?? fetch,
-      timeoutMs,
-      maxRetries,
-      userAgent: `sendora-sdk/${SDK_VERSION}`,
-    });
+    const transport = transportFor(
+      options.token,
+      options,
+      'Sendora needs a server key (sk_…); it is shown once when the server or the key is created.',
+    );
     this.email = new EmailResource(transport);
     this.broadcasts = new BroadcastsResource(transport);
     this.messages = new MessagesResource(transport);
@@ -89,6 +61,5 @@ export class Sendora {
     this.suppressions = new SuppressionsResource(transport);
     this.tokens = new TokensResource(transport);
     this.webhooks = new WebhooksResource(transport);
-    this.domains = new DomainsResource(transport);
   }
 }

package/src/domains.ts

@@ -7,7 +7,7 @@ import type {
   VerifiedDomain,
 } from './types.ts';
 
-/** The account's sending domains and the two DNS records each one needs. Any server's token manages them. */
+/** The account's sending domains and the two DNS records each one needs, managed with the account key; every server sends from them. */
 export class DomainsResource {
   readonly #transport: Transport;
 

package/src/error.ts

@@ -1,9 +1,10 @@
 import type { LimitScope, SuppressedRecipient, ValidationIssue } from './types.ts';
 
-/** Every code the API answers, the three the SDK raises when it never got a proper answer, and the two of the webhook verifier. */
+/** Every code the API answers, under either kind of key, the three the SDK raises when it never got a proper answer, and the two of the webhook verifier. */
 export type SendoraErrorCode =
   | 'invalid_request'
   | 'unauthorized'
+  | 'wrong_token_kind'
   | 'payment_required'
   | 'tenant_paused'
   | 'tenant_not_active'
@@ -18,6 +19,13 @@ export type SendoraErrorCode =
   | 'inbound_stream_exists'
   | 'default_stream'
   | 'last_token'
+  | 'token_limit'
+  | 'last_secret'
+  | 'secret_limit'
+  | 'server_exists'
+  | 'server_limit'
+  | 'server_reserved'
+  | 'server_in_flight'
   | 'request_too_large'
   | 'from_domain_not_verified'
   | 'stream_not_found'
@@ -47,6 +55,7 @@ export type SendoraErrorCode =
 const apiCodes: ReadonlySet<string> = new Set<SendoraErrorCode>([
   'invalid_request',
   'unauthorized',
+  'wrong_token_kind',
   'payment_required',
   'tenant_paused',
   'tenant_not_active',
@@ -61,6 +70,13 @@ const apiCodes: ReadonlySet<string> = new Set<SendoraErrorCode>([
   'inbound_stream_exists',
   'default_stream',
   'last_token',
+  'token_limit',
+  'last_secret',
+  'secret_limit',
+  'server_exists',
+  'server_limit',
+  'server_reserved',
+  'server_in_flight',
   'request_too_large',
   'from_domain_not_verified',
   'stream_not_found',
@@ -93,6 +109,7 @@ export interface SendoraErrorFields {
   cap?: number | null;
   used?: number | null;
   resetsAt?: string | null;
+  max?: number | null;
   issues?: ValidationIssue[];
   suppressed?: SuppressedRecipient[];
   streamId?: string | null;
@@ -132,6 +149,8 @@ export class SendoraError extends Error {
   readonly used: number | null;
   /** When the month counter resets, on monthly_cap_reached. */
   readonly resetsAt: string | null;
+  /** Live keys the server or the account may hold, on token_limit; servers the account may have, on server_limit; live secrets a webhook may hold, on secret_limit. */
+  readonly max: number | null;
   /** One entry per invalid field, on invalid_request. */
   readonly issues: ValidationIssue[];
   /** The recipients the server refused, on recipient_suppressed. */
@@ -151,6 +170,7 @@ export class SendoraError extends Error {
     this.cap = fields.cap ?? null;
     this.used = fields.used ?? null;
     this.resetsAt = fields.resetsAt ?? null;
+    this.max = fields.max ?? null;
     this.issues = fields.issues ?? [];
     this.suppressed = fields.suppressed ?? [];
     this.streamId = fields.streamId ?? null;
@@ -180,6 +200,7 @@ export class SendoraError extends Error {
       cap: this.cap,
       used: this.used,
       resetsAt: this.resetsAt,
+      max: this.max,
       issues: this.issues,
       suppressed: this.suppressed,
       streamId: this.streamId,
@@ -213,6 +234,7 @@ export function errorFromAnswer(
     cap: integerOf(answer.cap),
     used: integerOf(answer.used),
     resetsAt: typeof answer.resetsAt === 'string' ? answer.resetsAt : null,
+    max: integerOf(answer.max) ?? integerOf(answer.maxServers),
     issues,
     suppressed: Array.isArray(answer.suppressed) ? answer.suppressed.filter(isSuppressed) : [],
     streamId: code === 'recipient_suppressed' ? stringOf(answer.streamId) : null,

package/src/index.ts

@@ -1,4 +1,6 @@
-export { DEFAULT_BASE_URL, Sendora } from './client.ts';
+export { SendoraAccount } from './account.ts';
+export type { SendoraAccountOptions } from './account.ts';
+export { Sendora } from './client.ts';
 export type { SendoraOptions } from './client.ts';
 export type { BroadcastsResource } from './broadcasts.ts';
 export type { DomainsResource } from './domains.ts';
@@ -8,6 +10,9 @@ export type { SendoraErrorCode } from './error.ts';
 export type { InboundResource } from './inbound.ts';
 export type { InboundDomainsResource } from './inbound-domains.ts';
 export type { MessagesResource } from './messages.ts';
+export { DEFAULT_BASE_URL } from './options.ts';
+export type { ClientOptions } from './options.ts';
+export type { ServersResource, ServerTokensResource } from './servers.ts';
 export type { StreamsResource } from './streams.ts';
 export type { SuppressionsResource } from './suppressions.ts';
 export type { TokensResource } from './tokens.ts';

package/src/options.ts

@@ -0,0 +1,51 @@
+import { DEFAULT_MAX_RETRIES } from './retry.ts';
+import { Transport } from './transport.ts';
+import { SDK_VERSION } from './version.ts';
+
+export const DEFAULT_BASE_URL = 'https://api.sendora.se';
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** What both clients take besides the key. */
+export interface ClientOptions {
+  /** The API's origin; https://api.sendora.se unless you test against another. */
+  baseUrl?: string | undefined;
+  /** The fetch to use; the global one unless you need a proxy or a fake. */
+  fetch?: typeof fetch | undefined;
+  /** How long one attempt may take; 30 seconds by default. */
+  timeoutMs?: number | undefined;
+  /** How many times a failed call is repeated when repeating is safe; 2 by default, 0 turns retries off. */
+  maxRetries?: number | undefined;
+}
+
+/**
+ * The transport a client's resources share, built once at construction so
+ * a missing key or a nonsense option fails at startup rather than at the
+ * first call.
+ */
+export function transportFor(
+  token: string | undefined,
+  options: ClientOptions,
+  missingKey: string,
+): Transport {
+  if (token === undefined || token.trim() === '') {
+    throw new TypeError(missingKey);
+  }
+  const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+  new URL(baseUrl);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!(timeoutMs > 0)) {
+    throw new TypeError('timeoutMs must be a positive number of milliseconds.');
+  }
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+    throw new TypeError('maxRetries must be a whole number of zero or more.');
+  }
+  return new Transport({
+    baseUrl,
+    token,
+    fetch: options.fetch ?? fetch,
+    timeoutMs,
+    maxRetries,
+    userAgent: `sendora-sdk/${SDK_VERSION}`,
+  });
+}

package/src/servers.ts

@@ -0,0 +1,166 @@
+import type { Transport } from './transport.ts';
+import type {
+  CreatedServer,
+  CreatedToken,
+  CreateServerRequest,
+  CreateTokenRequest,
+  RequestOptions,
+  Server,
+  ServerList,
+  Token,
+  TokenList,
+  UpdateServerRequest,
+} from './types.ts';
+
+/**
+ * The keys of one server, managed with the account key. A server holds at
+ * most two live keys, so rotation is create, switch, revoke.
+ */
+export class ServerTokensResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * Creates another live key for the server and answers its value once; it
+   * is never shown again, so store it at once. A third live key is refused
+   * with `token_limit`.
+   *
+   * @example
+   * const { token } = await account.servers.tokens.create(serverId, { name: 'Fakturasystemet' });
+   */
+  create(
+    serverId: string,
+    request: CreateTokenRequest,
+    options: RequestOptions = {},
+  ): Promise<CreatedToken> {
+    return this.#transport.request<CreatedToken>({
+      method: 'POST',
+      path: `/v1/servers/${encodeURIComponent(serverId)}/tokens`,
+      body: request,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /** Every key of the server, revoked ones included. */
+  list(serverId: string, options: RequestOptions = {}): Promise<TokenList> {
+    return this.#transport.request<TokenList>({
+      method: 'GET',
+      path: `/v1/servers/${encodeURIComponent(serverId)}/tokens`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** One key by id; its value is never part of the answer. */
+  get(serverId: string, tokenId: string, options: RequestOptions = {}): Promise<Token> {
+    return this.#transport.request<Token>({
+      method: 'GET',
+      path: `/v1/servers/${encodeURIComponent(serverId)}/tokens/${encodeURIComponent(tokenId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * The key stops working at once. The last live key of a server cannot be
+   * revoked (`last_token`), so a server is never locked out.
+   *
+   * @example
+   * await account.servers.tokens.revoke(serverId, tokenId);
+   */
+  revoke(serverId: string, tokenId: string, options: RequestOptions = {}): Promise<void> {
+    return this.#transport.request<undefined>({
+      method: 'DELETE',
+      path: `/v1/servers/${encodeURIComponent(serverId)}/tokens/${encodeURIComponent(tokenId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}
+
+/** The account's servers: each an isolation boundary with its own keys, streams, log, suppressions and webhooks. */
+export class ServersResource {
+  readonly #transport: Transport;
+  /** The keys of each server. */
+  readonly tokens: ServerTokensResource;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+    this.tokens = new ServerTokensResource(transport);
+  }
+
+  /**
+   * Creates a server with its default transactional stream and its first
+   * key, whose value is answered this once. A taken name is
+   * `server_exists`; the account's cap is `server_limit` with `max`.
+   *
+   * @example
+   * const server = await account.servers.create({ name: 'Fakturering' });
+   * const sendora = new Sendora({ token: server.token.token });
+   */
+  create(request: CreateServerRequest, options: RequestOptions = {}): Promise<CreatedServer> {
+    return this.#transport.request<CreatedServer>({
+      method: 'POST',
+      path: '/v1/servers',
+      body: request,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /** Every server of the account, oldest first. */
+  list(options: RequestOptions = {}): Promise<ServerList> {
+    return this.#transport.request<ServerList>({
+      method: 'GET',
+      path: '/v1/servers',
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** One server by id. */
+  get(serverId: string, options: RequestOptions = {}): Promise<Server> {
+    return this.#transport.request<Server>({
+      method: 'GET',
+      path: `/v1/servers/${encodeURIComponent(serverId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** Renames the server; the id, the keys and everything it holds stay. A taken name is `server_exists`. */
+  update(
+    serverId: string,
+    request: UpdateServerRequest,
+    options: RequestOptions = {},
+  ): Promise<Server> {
+    return this.#transport.request<Server>({
+      method: 'PATCH',
+      path: `/v1/servers/${encodeURIComponent(serverId)}`,
+      body: request,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * Removes the server with its keys, streams, messages, suppressions and
+   * webhooks. Refused with `server_in_flight` while its messages are still
+   * being delivered; try again once they have left.
+   *
+   * @example
+   * await account.servers.delete(serverId);
+   */
+  delete(serverId: string, options: RequestOptions = {}): Promise<void> {
+    return this.#transport.request<undefined>({
+      method: 'DELETE',
+      path: `/v1/servers/${encodeURIComponent(serverId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}

package/src/types.ts

@@ -586,13 +586,13 @@ export interface BroadcastPage {
 /** What `broadcasts.list` takes. */
 export type BroadcastList = PageQuery;
 
-/** The body POST /v1/tokens takes. */
+/** The body POST /v1/tokens and POST /v1/servers/{id}/tokens take. */
 export interface CreateTokenRequest {
   /** 1 to 100 characters, for people to tell tokens apart. */
   name: string;
 }
 
-/** A token of the server; its value is shown only when it is created. */
+/** A key of a server; its value is shown only when it is created. */
 export interface Token {
   tokenId: string;
   name: string;
@@ -602,7 +602,7 @@ export interface Token {
   revokedAt: string | null;
 }
 
-/** A token just created, with its value, shown this once. */
+/** A key just created, with its value, shown this once. */
 export interface CreatedToken extends Token {
   token: string;
 }
@@ -611,6 +611,37 @@ export interface TokenList {
   tokens: Token[];
 }
 
+/** A server of the account: an isolation boundary with its own keys, streams, log, suppressions and webhooks. */
+export interface Server {
+  /** The id every server key, stream and message of the server refers to. */
+  serverId: string;
+  /** The name given at creation, unique within the account. */
+  name: string;
+  createdAt: string;
+}
+
+/** A server just created, with its first key, whose value is shown this once. */
+export interface CreatedServer extends Server {
+  /** The server's first key, named default; its value is never shown again. */
+  token: CreatedToken;
+}
+
+export interface ServerList {
+  servers: Server[];
+}
+
+/** The body POST /v1/servers takes. */
+export interface CreateServerRequest {
+  /** 1 to 100 characters, unique within the account. */
+  name: string;
+}
+
+/** The body PATCH /v1/servers/{id} takes. */
+export interface UpdateServerRequest {
+  /** 1 to 100 characters, unique within the account. */
+  name: string;
+}
+
 /** The events a webhook can receive. */
 export type WebhookEventName =
   | 'delivered'
@@ -649,6 +680,19 @@ export interface Webhook {
   /** How the inbound event carries a received message: the parsed message, or a reference. */
   inboundContent: InboundContent;
   createdAt: string;
+  /** The live secrets, oldest first; every delivery is signed with each of them, the newest first in Sendora-Signature. */
+  secrets: WebhookSecret[];
+}
+
+/** A live signing secret of a webhook by id and age; its value was shown once when it was created. */
+export interface WebhookSecret {
+  secretId: string;
+  createdAt: string;
+}
+
+/** A secret just created, with its value, shown this once. */
+export interface CreatedWebhookSecret extends WebhookSecret {
+  secret: string;
 }
 
 /** A webhook just created, with its signing secret, shown this once. */

package/src/version.ts

@@ -1,2 +1,2 @@
 /** The package version, sent as the User-Agent; a test holds it equal to package.json. */
-export const SDK_VERSION = '1.2.0';
+export const SDK_VERSION = '2.1.0';