@kaviox/auth 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -113,6 +113,33 @@ Workers that import `@kaviox/auth/mcp` log one warning per isolate, "CIMD (Clien
113
113
  Document) is disabled". It comes from the OAuth library and matters only to an authorization
114
114
  server, which here is the gateway. Apps don't need that compatibility flag.
115
115
 
116
+ ## Email
117
+
118
+ When the app's `apps.json` entry has `"mail": { "from": "<address>@kaviox.com" }`, the platform
119
+ also adds a `KAVIOX_MAIL` binding. The gateway sends from that address; the app picks the rest.
120
+
121
+ ```ts
122
+ import type { MailBinding } from '@kaviox/auth';
123
+
124
+ type Env = { KAVIOX_MAIL: MailBinding };
125
+
126
+ const { messageId } = await env.KAVIOX_MAIL.send({
127
+ to: 'person@example.com', // or up to 50 addresses
128
+ subject: 'You are invited to Build',
129
+ text: 'Open https://app.build.kaviox.com/invite/… to join.',
130
+ html: '<p>…</p>', // optional
131
+ replyTo: 'pm@example.com', // optional
132
+ fromName: 'Elevate Design Build', // optional display name; default the repository name
133
+ });
134
+ ```
135
+
136
+ Failures reject with an `Error` whose message starts with a code: `E_VALIDATION_ERROR`,
137
+ `E_CONTENT_TOO_LARGE`, `E_RATE_LIMIT_EXCEEDED` (60 a minute per app), `E_MAIL_NOT_ALLOWED`,
138
+ `E_MAIL_NOT_SET_UP`, or Email Service's own, such as `E_RECIPIENT_SUPPRESSED`,
139
+ `E_DAILY_LIMIT_EXCEEDED` and `E_SENDER_NOT_VERIFIED` (the domain isn't onboarded yet). Read it
140
+ with `error.message.split(':')[0]`. On staging and previews the subject starts with `[Test] `.
141
+ See [Email](https://github.com/kaviox/platform/blob/main/docs/sign-in-gateway.md#email).
142
+
116
143
  ## Development
117
144
 
118
145
  ```bash
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { safeReturnTo } from './return-to.ts';
2
2
  import type { Provider } from './types.ts';
3
- export type { GatewayBinding, Identity, Provider, ValidatedToken } from './types.ts';
3
+ export type { GatewayBinding, Identity, MailBinding, MailMessage, Provider, ValidatedToken } from './types.ts';
4
4
  export { safeReturnTo };
5
5
  export declare const PATHS: {
6
6
  readonly signIn: "/auth/signin";
package/dist/types.d.ts CHANGED
@@ -44,3 +44,26 @@ export interface GatewayBinding {
44
44
  /** Checks a bearer token for one of the app's MCP resources. */
45
45
  validateToken(resource: string, token: string): Promise<ValidatedToken | null>;
46
46
  }
47
+ /** One transactional email. The gateway sends it from the app's address in apps.json. */
48
+ export interface MailMessage {
49
+ /** 1 to 50 addresses. */
50
+ to: string | string[];
51
+ /** Up to 998 characters, on one line. The staging gateway adds "[Test] " in front. */
52
+ subject: string;
53
+ /** The plain-text body. Required, so every message reads in any mail client. */
54
+ text: string;
55
+ html?: string;
56
+ replyTo?: string;
57
+ /** The sender's display name. Defaults to the app's repository name. */
58
+ fromName?: string;
59
+ }
60
+ /**
61
+ * The gateway's mail binding, which the platform adds to every deploy of an app with "mail" in
62
+ * apps.json (as KAVIOX_MAIL). Failures reject with an Error whose message starts with a code, as
63
+ * in "E_RECIPIENT_SUPPRESSED: …" (see the package README).
64
+ */
65
+ export interface MailBinding {
66
+ send(message: MailMessage): Promise<{
67
+ messageId: string;
68
+ }>;
69
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kaviox/auth",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Sign-in for Kaviox apps on Cloudflare Workers, through the Kaviox sign-in gateway: middleware, callback, sign-out, sessions and MCP token checks.",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",