@fabrika/control-contract 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/control-contract",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -25,8 +25,8 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth-core": "0.6.0",
-		"@fabrika/app": "0.6.0",
-		"@fabrika/provider-contract": "0.6.0"
+		"@fabrika/auth-core": "0.7.0",
+		"@fabrika/app": "0.7.0",
+		"@fabrika/provider-contract": "0.7.0"
 	}
 }

package/src/access.ts

@@ -36,6 +36,15 @@ export const CONTROL_ACTIONS = Object.freeze({
 	 * the operator role does not hold it; only a human user principal in the console may use it. Scoped by app/environment.
 	 */
 	ACCESS_APPROVE: 'access.approve',
+	/**
+	 * List relayed mail and read its metadata. Scoped by app/environment for an application's messages; an installation
+	 * sender's messages need a global grant.
+	 */
+	MAIL_READ: 'mail.read',
+	/** Read a relayed message's recipient, subject and bodies. Global. */
+	MAIL_CONTENT_READ: 'mail.content.read',
+	/** Release or drop a held message, requeue a final one, and change the gate's rules. Global. */
+	MAIL_MANAGE: 'mail.manage',
 })
 
 /**

package/src/index.ts

@@ -6,6 +6,7 @@ export * from './access.js'
 export * from './builder-bootstrap.js'
 export * from './builder-connections.js'
 export * from './builder-pairing.js'
+export * from './mail.js'
 
 export type { JsonValue }
 
@@ -566,6 +567,7 @@ export type {
 	PutAppEnvironmentInput,
 	PutAppSecretInput,
 	PutAppVarInput,
+	RotateTokenKeyResponse,
 	RunIdInput,
 	RunListInput,
 	SecretValueInput,

package/src/mail.ts

@@ -0,0 +1,96 @@
+/** The mail relay as the console reads and steers it. */
+
+/**
+ * `held` waits for a person, `queued` for the dispatcher, `sending` is one attempt a dispatcher claimed. `sent`,
+ * `failed` (not sent), `unknown` (may have left) and `dropped` are final.
+ */
+export type MailMessageState = 'held' | 'queued' | 'sending' | 'sent' | 'failed' | 'unknown' | 'dropped'
+
+export type MailRuleAction = 'pass' | 'hold' | 'drop'
+
+/** A relayed message's metadata, behind `mail.read`. It carries no recipient, subject or body. */
+export interface MailMessageDto {
+	readonly id: string
+	/** `<app>@<env>`, or `installation:<service>` for an installation sender. */
+	readonly sender: string
+	readonly recipientDomain: string
+	readonly state: MailMessageState
+	/** The rule that decided the message at acceptance; null when none did. */
+	readonly ruleId: string | null
+	/** Who released or dropped it, or requeued it once it was final. */
+	readonly decidedBy: string | null
+	readonly attempts: number
+	readonly nextAttemptAt: number | null
+	readonly providerMessageId: string | null
+	/**
+	 * The `EmailDeliveryErrorCode` of the last failed attempt, or `dispatch_interrupted`: the dispatcher stopped after it
+	 * claimed the attempt, before it recorded an outcome.
+	 */
+	readonly errorCode: string | null
+	readonly createdAt: number
+	readonly updatedAt: number
+}
+
+/** One attachment as the console shows it: its name, type and size, never its bytes. */
+export interface MailAttachmentDto {
+	readonly filename: string
+	readonly contentType: string
+	readonly bytes: number
+}
+
+/** What the recipient sees, behind `mail.content.read`. */
+export interface MailMessageContentDto {
+	readonly to: string
+	readonly subject: string
+	readonly text: string
+	readonly html?: string
+	readonly replyTo?: string
+	readonly fromName?: string
+	readonly unsubscribeUrl?: string
+	readonly attachments: readonly MailAttachmentDto[]
+}
+
+/** `withheld`: the caller does not hold `mail.content.read`. `purged`: the relay no longer keeps it. */
+export type MailContentDto =
+	| { readonly kind: 'withheld' }
+	| { readonly kind: 'purged' }
+	| { readonly kind: 'present'; readonly message: MailMessageContentDto }
+
+export interface MailMessageDetailDto extends MailMessageDto {
+	readonly content: MailContentDto
+	/** Whether a requeue would send it again now: `failed`, or `unknown` over an idempotent transport, with its content kept. */
+	readonly requeueable: boolean
+}
+
+export interface MailMessageListInput {
+	readonly state?: MailMessageState
+	/** One sender: `<app>@<env>` or `installation:<service>`. */
+	readonly scope?: string
+	readonly cursor?: string
+}
+
+export interface MailMessageIdInput {
+	readonly id: string
+}
+
+export interface MailRuleDto {
+	readonly id: string
+	/** `*` or `<app>@<env>`. */
+	readonly scope: string
+	/** `*` or a lowercase recipient domain. */
+	readonly domain: string
+	readonly action: MailRuleAction
+	readonly createdAt: number
+	readonly updatedAt: number
+}
+
+/** Sets the action of the rule of `scope` and `domain`, creating it when there is none. */
+export interface SetMailRuleInput {
+	readonly scope: string
+	readonly domain: string
+	readonly action: MailRuleAction
+}
+
+export interface MailRuleIdInput {
+	readonly id: string
+}

package/src/rpc.ts

@@ -47,6 +47,15 @@ import type {
 	UpdateAppRequest,
 	UpdateDeploymentNamespaceRequest,
 } from './index.js'
+import type {
+	MailMessageDetailDto,
+	MailMessageDto,
+	MailMessageIdInput,
+	MailMessageListInput,
+	MailRuleDto,
+	MailRuleIdInput,
+	SetMailRuleInput,
+} from './mail.js'
 
 type RpcProcedure<TInput, TOutput> = RpcProcedureContract<TInput, TOutput>
 
@@ -54,6 +63,11 @@ export interface AppIdInput {
 	readonly appId: string
 }
 
+/** Whether a rotation was recorded: `false` while the environment holds no token key. */
+export interface RotateTokenKeyResponse {
+	readonly requested: boolean
+}
+
 export interface AppEnvironmentInput extends AppIdInput {
 	readonly env: string
 }
@@ -161,6 +175,8 @@ export interface ControlRpcContract {
 			delete: RpcProcedure<AppEnvironmentInput, OkResponse>
 			/** Human user principals with `access.approve` only, from the console (ADR-0050 §4). */
 			protect: RpcProcedure<SetEnvironmentProtectionRequest, AppEnvDto>
+			/** The environment's next deploy retires the key its signed tokens are signed with and signs with a new one. */
+			rotateTokenKey: RpcProcedure<AppEnvironmentInput, RotateTokenKeyResponse>
 		}
 		secrets: {
 			list: RpcProcedure<AppIdInput, ListResponse<AppSecretDto>>
@@ -214,6 +230,25 @@ export interface ControlRpcContract {
 	connectors: {
 		describe: RpcProcedure<DescribeConnectorRequest, ExportDescription>
 	}
+	/** The mail relay: `mail.read`, `mail.content.read` and `mail.manage`. */
+	mail: {
+		messages: {
+			list: RpcProcedure<MailMessageListInput, CursorList<MailMessageDto>>
+			/** The content only with `mail.content.read`. */
+			get: RpcProcedure<MailMessageIdInput, MailMessageDetailDto>
+			/** A held message only. */
+			release: RpcProcedure<MailMessageIdInput, MailMessageDto>
+			/** A held message only. */
+			drop: RpcProcedure<MailMessageIdInput, MailMessageDto>
+			/** A `failed` message, or an `unknown` one over an idempotent transport, whose content is kept. */
+			requeue: RpcProcedure<MailMessageIdInput, MailMessageDto>
+		}
+		rules: {
+			list: RpcProcedure<void, ListResponse<MailRuleDto>>
+			set: RpcProcedure<SetMailRuleInput, MailRuleDto>
+			remove: RpcProcedure<MailRuleIdInput, OkResponse>
+		}
+	}
 }
 
 /**