@workwae/sdk 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -1,6 +1,6 @@
 # @workwae/sdk
 
-The TypeScript client for the [workwae](https://workwae.com) API: one REST API for Gmail,
+The TypeScript client for the [Workwae](https://workwae.com) API: one REST API for Gmail,
 Microsoft 365 and IMAP mailboxes, Google, Microsoft and CalDAV calendars, and contacts. Every
 method, input, answer and error is typed from the same contract the API is built on.
 
@@ -11,8 +11,8 @@ method, input, answer and error is typed from the same contract the API is built
 - Idempotency keys on every POST
 - Webhook signature verification (Standard Webhooks) and typed event parsing
 
-The full guides and API reference are in the board's docs, at `/docs` (`/docs/api` for every
-operation, `/docs/changelog` for what changed).
+The full guides and API reference are at https://docs.workwae.com (`/reference` for every
+operation, `/changelog` for what changed).
 
 ## Install
 
@@ -57,7 +57,7 @@ const queued = await workwae.outbox.create({
   accountId,
   to: [{ name: "Ada Lovelace", address: "ada@example.com" }],
   subject: "Hello",
-  text: "Sent with workwae.",
+  text: "Sent with Workwae.",
 });
 ```
 
@@ -78,7 +78,7 @@ await workwae.accounts.list({}, { signal: controller.signal });
 
 ## Authentication
 
-API keys are created on the board under **API keys**, with the scopes the integration needs
+API keys are created on the console under **API keys**, with the scopes the integration needs
 (`read`, `write`, `send`, `admin`). They reach every account of the tenant, so keep them on your
 server.
 
@@ -190,7 +190,7 @@ repeat while the first call still runs with `idempotency_key_in_progress`.
 
 ## Webhooks
 
-workwae signs deliveries with [Standard Webhooks](https://www.standardwebhooks.com/).
+Workwae signs deliveries with [Standard Webhooks](https://www.standardwebhooks.com/).
 `parseWebhook` verifies a delivery and returns its event, typed by `type`, with dates as `Date`.
 Pass the raw body exactly as received:
 
@@ -231,4 +231,4 @@ import type { Account, CalendarEvent, Event, EventType, Message, OutboxEntry } f
 ## Versioning
 
 The SDK follows semver from 0.1.0; while it is 0.x, a minor version may carry breaking changes,
-always listed in the changelog. Releases are tagged `sdk-v<version>` in the repository.
+always listed in the [changelog](https://docs.workwae.com/changelog).

package/client.d.ts

@@ -32,5 +32,5 @@ export interface ClientOptions {
     fetch?: (request: Request, init?: RequestInit) => Promise<Response>;
     retry?: RetryOptions;
 }
-/** A typed client for the workwae /v1 API. */
+/** A typed client for the Workwae /v1 API. */
 export declare function createClient(options: ClientOptions): WorkwaeClient;

package/contract/accounts/models.d.ts

@@ -4,7 +4,6 @@ export declare const OAuthProvider: z.ZodEnum<{
     microsoft: "microsoft";
 }>;
 export type OAuthProvider = z.infer<typeof OAuthProvider>;
-/** Microsoft 365 cloud. GCC (moderate) is "global"; GCC High, DoD and 21Vianet have their own. */
 export declare const MicrosoftCloud: z.ZodEnum<{
     global: "global";
     "gcc-high": "gcc-high";
@@ -25,7 +24,6 @@ export declare const AccountStatus: z.ZodEnum<{
     disabled: "disabled";
 }>;
 export type AccountStatus = z.infer<typeof AccountStatus>;
-/** The statuses a caller may set; the others are set by the platform. */
 export declare const SettableAccountStatus: z.ZodEnum<{
     active: "active";
     paused: "paused";
@@ -52,8 +50,6 @@ export declare const AccountRuntime: z.ZodObject<{
     updatedAt: z.ZodPreprocess<z.ZodDate, Date>;
 }, z.core.$strip>;
 export type AccountRuntime = z.infer<typeof AccountRuntime>;
-/** tls: implicit TLS (993/465). starttls: upgrade after connect (143/587). none: plaintext,
- * accepted only by instances that allow it (local test servers). */
 export declare const MailSecurity: z.ZodEnum<{
     none: "none";
     tls: "tls";
@@ -71,17 +67,11 @@ export declare const MailServer: z.ZodObject<{
     user: z.ZodString;
 }, z.core.$strip>;
 export type MailServer = z.infer<typeof MailServer>;
-/** imap_password: DAV logs in with the IMAP password (what app passwords cover on iCloud, Fastmail
- * and Yahoo); dav_password: with a separate one. */
 export declare const DavAuth: z.ZodEnum<{
     imap_password: "imap_password";
     dav_password: "dav_password";
 }>;
 export type DavAuth = z.infer<typeof DavAuth>;
-/**
- * CalDAV and CardDAV of an IMAP account: the calendar and address book home sets (null: that half
- * is not used) and the login.
- */
 export declare const DavSettings: z.ZodObject<{
     calendarUrl: z.ZodNullable<z.ZodString>;
     contactsUrl: z.ZodNullable<z.ZodString>;
@@ -92,14 +82,12 @@ export declare const DavSettings: z.ZodObject<{
     }>;
 }, z.core.$strip>;
 export type DavSettings = z.infer<typeof DavSettings>;
-/** password, or OAuth tokens from this provider (XOAUTH2). */
 export declare const ImapAuth: z.ZodEnum<{
     google: "google";
     microsoft: "microsoft";
     password: "password";
 }>;
 export type ImapAuth = z.infer<typeof ImapAuth>;
-/** An IMAP account's servers; secrets are never returned. */
 export declare const ImapSettings: z.ZodObject<{
     imap: z.ZodObject<{
         host: z.ZodString;
@@ -138,21 +126,13 @@ export declare const ImapSettings: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ImapSettings = z.infer<typeof ImapSettings>;
-/**
- * How an account authenticates:
- * - oauth: its own user grant (a refresh token from a connect flow).
- * - password: an IMAP/SMTP password.
- * - google_delegation / microsoft_app: the organization connection `orgConnectionId` (Google
- *   domain-wide delegation, Microsoft app-only); nobody signed in.
- * - shared_mailbox: the delegated grant of account `delegateAccountId`, opening a mailbox that
- *   account's user has access to.
- */
 export declare const AccountAuthMethod: z.ZodEnum<{
     password: "password";
     oauth: "oauth";
     google_delegation: "google_delegation";
     microsoft_app: "microsoft_app";
     shared_mailbox: "shared_mailbox";
+    google_group: "google_group";
 }>;
 export type AccountAuthMethod = z.infer<typeof AccountAuthMethod>;
 export declare const AccountAuth: z.ZodObject<{
@@ -162,9 +142,11 @@ export declare const AccountAuth: z.ZodObject<{
         google_delegation: "google_delegation";
         microsoft_app: "microsoft_app";
         shared_mailbox: "shared_mailbox";
+        google_group: "google_group";
     }>;
     orgConnectionId: z.ZodNullable<z.ZodUUID>;
     delegateAccountId: z.ZodNullable<z.ZodUUID>;
+    relayEmail: z.ZodNullable<z.ZodEmail>;
 }, z.core.$strip>;
 export type AccountAuth = z.infer<typeof AccountAuth>;
 export declare const Account: z.ZodObject<{
@@ -198,12 +180,18 @@ export declare const Account: z.ZodObject<{
             full: "full";
         }>;
         syncWindowDays: z.ZodNullable<z.ZodNumber>;
+        mailEnabled: z.ZodBoolean;
         calendarEnabled: z.ZodBoolean;
         contactsEnabled: z.ZodBoolean;
         undoSendSeconds: z.ZodNumber;
         trackOpens: z.ZodBoolean;
         trackClicks: z.ZodBoolean;
         trackingHoneypot: z.ZodBoolean;
+        suppressionCheck: z.ZodEnum<{
+            lists: "lists";
+            always: "always";
+        }>;
+        sendsPerMinute: z.ZodNullable<z.ZodNumber>;
     }, z.core.$strip>;
     settingsOverride: z.ZodObject<{
         bodyStorage: z.ZodOptional<z.ZodEnum<{
@@ -212,12 +200,18 @@ export declare const Account: z.ZodObject<{
             full: "full";
         }>>;
         syncWindowDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        mailEnabled: z.ZodOptional<z.ZodBoolean>;
         calendarEnabled: z.ZodOptional<z.ZodBoolean>;
         contactsEnabled: z.ZodOptional<z.ZodBoolean>;
         undoSendSeconds: z.ZodOptional<z.ZodNumber>;
         trackOpens: z.ZodOptional<z.ZodBoolean>;
         trackClicks: z.ZodOptional<z.ZodBoolean>;
         trackingHoneypot: z.ZodOptional<z.ZodBoolean>;
+        suppressionCheck: z.ZodOptional<z.ZodEnum<{
+            lists: "lists";
+            always: "always";
+        }>>;
+        sendsPerMinute: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>;
     runtime: z.ZodNullable<z.ZodObject<{
         state: z.ZodEnum<{
@@ -275,9 +269,11 @@ export declare const Account: z.ZodObject<{
             google_delegation: "google_delegation";
             microsoft_app: "microsoft_app";
             shared_mailbox: "shared_mailbox";
+            google_group: "google_group";
         }>;
         orgConnectionId: z.ZodNullable<z.ZodUUID>;
         delegateAccountId: z.ZodNullable<z.ZodUUID>;
+        relayEmail: z.ZodNullable<z.ZodEmail>;
     }, z.core.$strip>;
     initializedAt: z.ZodNullable<z.ZodPreprocess<z.ZodDate, Date>>;
     calendarInitializedAt: z.ZodNullable<z.ZodPreprocess<z.ZodDate, Date>>;
@@ -286,6 +282,28 @@ export declare const Account: z.ZodObject<{
     updatedAt: z.ZodPreprocess<z.ZodDate, Date>;
 }, z.core.$strip>;
 export type Account = z.infer<typeof Account>;
+export declare const SyncKind: z.ZodEnum<{
+    mail: "mail";
+    calendar: "calendar";
+    contacts: "contacts";
+}>;
+export type SyncKind = z.infer<typeof SyncKind>;
+export declare const SyncAccountRequest: z.ZodObject<{
+    kinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        mail: "mail";
+        calendar: "calendar";
+        contacts: "contacts";
+    }>>>;
+}, z.core.$strip>;
+export type SyncAccountRequest = z.infer<typeof SyncAccountRequest>;
+export declare const AccountSyncQueued: z.ZodObject<{
+    kinds: z.ZodArray<z.ZodEnum<{
+        mail: "mail";
+        calendar: "calendar";
+        contacts: "contacts";
+    }>>;
+}, z.core.$strip>;
+export type AccountSyncQueued = z.infer<typeof AccountSyncQueued>;
 export declare const AccountPage: z.ZodObject<{
     items: z.ZodArray<z.ZodObject<{
         id: z.ZodUUID;
@@ -318,12 +336,18 @@ export declare const AccountPage: z.ZodObject<{
                 full: "full";
             }>;
             syncWindowDays: z.ZodNullable<z.ZodNumber>;
+            mailEnabled: z.ZodBoolean;
             calendarEnabled: z.ZodBoolean;
             contactsEnabled: z.ZodBoolean;
             undoSendSeconds: z.ZodNumber;
             trackOpens: z.ZodBoolean;
             trackClicks: z.ZodBoolean;
             trackingHoneypot: z.ZodBoolean;
+            suppressionCheck: z.ZodEnum<{
+                lists: "lists";
+                always: "always";
+            }>;
+            sendsPerMinute: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strip>;
         settingsOverride: z.ZodObject<{
             bodyStorage: z.ZodOptional<z.ZodEnum<{
@@ -332,12 +356,18 @@ export declare const AccountPage: z.ZodObject<{
                 full: "full";
             }>>;
             syncWindowDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            mailEnabled: z.ZodOptional<z.ZodBoolean>;
             calendarEnabled: z.ZodOptional<z.ZodBoolean>;
             contactsEnabled: z.ZodOptional<z.ZodBoolean>;
             undoSendSeconds: z.ZodOptional<z.ZodNumber>;
             trackOpens: z.ZodOptional<z.ZodBoolean>;
             trackClicks: z.ZodOptional<z.ZodBoolean>;
             trackingHoneypot: z.ZodOptional<z.ZodBoolean>;
+            suppressionCheck: z.ZodOptional<z.ZodEnum<{
+                lists: "lists";
+                always: "always";
+            }>>;
+            sendsPerMinute: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$strip>;
         runtime: z.ZodNullable<z.ZodObject<{
             state: z.ZodEnum<{
@@ -395,9 +425,11 @@ export declare const AccountPage: z.ZodObject<{
                 google_delegation: "google_delegation";
                 microsoft_app: "microsoft_app";
                 shared_mailbox: "shared_mailbox";
+                google_group: "google_group";
             }>;
             orgConnectionId: z.ZodNullable<z.ZodUUID>;
             delegateAccountId: z.ZodNullable<z.ZodUUID>;
+            relayEmail: z.ZodNullable<z.ZodEmail>;
         }, z.core.$strip>;
         initializedAt: z.ZodNullable<z.ZodPreprocess<z.ZodDate, Date>>;
         calendarInitializedAt: z.ZodNullable<z.ZodPreprocess<z.ZodDate, Date>>;
@@ -423,7 +455,6 @@ export declare const ListAccountsQuery: z.ZodObject<{
     cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ListAccountsQuery = z.infer<typeof ListAccountsQuery>;
-/** Headless connect with tokens the tenant already holds (typically from its own OAuth app). */
 export declare const CreateAccount: z.ZodObject<{
     provider: z.ZodEnum<{
         google: "google";
@@ -445,12 +476,18 @@ export declare const CreateAccount: z.ZodObject<{
             full: "full";
         }>>;
         syncWindowDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        mailEnabled: z.ZodOptional<z.ZodBoolean>;
         calendarEnabled: z.ZodOptional<z.ZodBoolean>;
         contactsEnabled: z.ZodOptional<z.ZodBoolean>;
         undoSendSeconds: z.ZodOptional<z.ZodNumber>;
         trackOpens: z.ZodOptional<z.ZodBoolean>;
         trackClicks: z.ZodOptional<z.ZodBoolean>;
         trackingHoneypot: z.ZodOptional<z.ZodBoolean>;
+        suppressionCheck: z.ZodOptional<z.ZodEnum<{
+            lists: "lists";
+            always: "always";
+        }>>;
+        sendsPerMinute: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>>;
     sharedMailboxesEnabled: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
@@ -468,32 +505,43 @@ export declare const UpdateAccount: z.ZodObject<{
             full: "full";
         }>>;
         syncWindowDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        mailEnabled: z.ZodOptional<z.ZodBoolean>;
         calendarEnabled: z.ZodOptional<z.ZodBoolean>;
         contactsEnabled: z.ZodOptional<z.ZodBoolean>;
         undoSendSeconds: z.ZodOptional<z.ZodNumber>;
         trackOpens: z.ZodOptional<z.ZodBoolean>;
         trackClicks: z.ZodOptional<z.ZodBoolean>;
         trackingHoneypot: z.ZodOptional<z.ZodBoolean>;
+        suppressionCheck: z.ZodOptional<z.ZodEnum<{
+            lists: "lists";
+            always: "always";
+        }>>;
+        sendsPerMinute: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type UpdateAccount = z.infer<typeof UpdateAccount>;
 export declare const DeleteAccountQuery: z.ZodObject<{
-    purge: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
-        true: "true";
-        false: "false";
-    }>]>, z.ZodTransform<boolean, boolean | "true" | "false">>>;
+    purge: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [
+        z.ZodBoolean,
+        z.ZodEnum<{
+            true: "true";
+            false: "false";
+        }>
+    ]>, z.ZodTransform<boolean, boolean | "true" | "false">>>;
 }, z.core.$strip>;
 export type DeleteAccountQuery = z.infer<typeof DeleteAccountQuery>;
-/** The path's account and the query's options, as a DELETE takes them. */
 export declare const DeleteAccountInput: z.ZodObject<{
     params: z.ZodObject<{
         accountId: z.ZodUUID;
     }, z.core.$strip>;
     query: z.ZodObject<{
-        purge: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
-            true: "true";
-            false: "false";
-        }>]>, z.ZodTransform<boolean, boolean | "true" | "false">>>;
+        purge: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [
+            z.ZodBoolean,
+            z.ZodEnum<{
+                true: "true";
+                false: "false";
+            }>
+        ]>, z.ZodTransform<boolean, boolean | "true" | "false">>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type DeleteAccountInput = z.infer<typeof DeleteAccountInput>;
@@ -501,7 +549,6 @@ export declare const MintAccountTokenRequest: z.ZodObject<{
     ttlSeconds: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type MintAccountTokenRequest = z.infer<typeof MintAccountTokenRequest>;
-/** Short-lived token limited to one account, for a tenant's own frontend. */
 export declare const AccountToken: z.ZodObject<{
     token: z.ZodString;
     expiresAt: z.ZodPreprocess<z.ZodDate, Date>;
@@ -518,13 +565,6 @@ export declare const MailServerInput: z.ZodObject<{
     user: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type MailServerInput = z.infer<typeof MailServerInput>;
-/**
- * CalDAV and CardDAV for the account. A URL may be any URL on the server (its root, the
- * principal, a calendar); the principal's calendar or address book home set is what is stored.
- * null turns that half off. Left out: discovered from the address (a built-in provider table,
- * /.well-known/caldav and /.well-known/carddav, then _caldavs._tcp and _carddavs._tcp SRV
- * records), or on an update of an account that has DAV settings, kept as stored.
- */
 export declare const DavInput: z.ZodObject<{
     calendarUrl: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
     contactsUrl: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
@@ -532,7 +572,6 @@ export declare const DavInput: z.ZodObject<{
     password: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type DavInput = z.infer<typeof DavInput>;
-/** An IMAP/SMTP account and its login, as the API and the hosted page's form take it. */
 export declare const ImapAccountInput: z.ZodObject<{
     email: z.ZodEmail;
     displayName: z.ZodOptional<z.ZodString>;
@@ -607,12 +646,18 @@ export declare const CreateImapAccount: z.ZodObject<{
             full: "full";
         }>>;
         syncWindowDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        mailEnabled: z.ZodOptional<z.ZodBoolean>;
         calendarEnabled: z.ZodOptional<z.ZodBoolean>;
         contactsEnabled: z.ZodOptional<z.ZodBoolean>;
         undoSendSeconds: z.ZodOptional<z.ZodNumber>;
         trackOpens: z.ZodOptional<z.ZodBoolean>;
         trackClicks: z.ZodOptional<z.ZodBoolean>;
         trackingHoneypot: z.ZodOptional<z.ZodBoolean>;
+        suppressionCheck: z.ZodOptional<z.ZodEnum<{
+            lists: "lists";
+            always: "always";
+        }>>;
+        sendsPerMinute: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CreateImapAccount = z.infer<typeof CreateImapAccount>;
@@ -648,14 +693,12 @@ export declare const UpdateImapSettings: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type UpdateImapSettings = z.infer<typeof UpdateImapSettings>;
-/** Where DAV context URLs were found: the built-in provider table, /.well-known, or SRV records. */
 export declare const DavDiscoverySource: z.ZodEnum<{
     provider: "provider";
     "well-known": "well-known";
     srv: "srv";
 }>;
 export type DavDiscoverySource = z.infer<typeof DavDiscoverySource>;
-/** DAV context URLs found for an address before logging in; setup follows them to the home sets. */
 export declare const DiscoveredDav: z.ZodObject<{
     source: z.ZodEnum<{
         provider: "provider";
@@ -666,7 +709,6 @@ export declare const DiscoveredDav: z.ZodObject<{
     contactsUrl: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type DiscoveredDav = z.infer<typeof DiscoveredDav>;
-/** Where mail server settings were found. */
 export declare const AutoconfigSource: z.ZodEnum<{
     provider: "provider";
     srv: "srv";
@@ -675,8 +717,6 @@ export declare const AutoconfigSource: z.ZodEnum<{
     mx: "mx";
 }>;
 export type AutoconfigSource = z.infer<typeof AutoconfigSource>;
-/** Servers found for an address; `oauth` names the provider whose sign-in reaches this mailbox,
- * which should be preferred over a password where the provider offers it. */
 export declare const DiscoveredSettings: z.ZodObject<{
     source: z.ZodEnum<{
         provider: "provider";